Configure Node.js and npm environment

Node.js and npm are core tools in the uni-app development toolchain. Proper environment configuration can significantly improve development efficiency and avoid compatibility issues caused by version mismatches.

Installing Node.js

Node.js is a server-side runtime for JavaScript and a dependency for npm. Recommended installation methods:

1. Official Installer (Recommended for beginners):

   • Visit the Node.js official website to download the LTS version
   • Windows users: Run the .msi installer
   • macOS users: Use the .pkg installer

2. Version Management Tools (For multi-project collaboration):

   # Using nvm (Windows users: nvm-windows)
   nvm install 16.14.0  # Install a specific version
   nvm use 16.14.0      # Switch versions
   

Post-installation verification:

node -v  # Should output e.g., v16.14.0
npm -v   # Corresponding version like 8.3.1

Configuring npm Mirror Source

For users in China, it's recommended to use the Taobao mirror for faster dependency downloads:

# Permanently set the mirror source
npm config set registry https://registry.npmmirror.com

# Temporarily use the mirror for installation
npm install --registry=https://registry.npmmirror.com

# Verify configuration
npm config get registry

Optional tool nrm for quick source switching:

npm install -g nrm
nrm ls           # List available sources
nrm use taobao   # Switch to Taobao source

Global Dependency Installation

Essential global tools for uni-app development:

# Vue CLI (Build tool)
npm install -g @vue/cli

# HBuilderX CLI tool (Optional)
npm install -g @dcloudio/uvm

# Verify installation
vue --version
uvm --version

Project-Level npm Configuration

Notes when creating a uni-app project:

1. Create via official template:

vue create -p dcloudio/uni-preset-vue my-project

2. Key package.json configuration example:

{
  "scripts": {
    "serve": "npm run dev:h5",
    "build": "npm run build:h5",
    "dev:h5": "uni -p h5",
    "build:h5": "uni build -p h5"
  },
  "dependencies": {
    "@dcloudio/uni-app": "^3.0.0",
    "sass": "^1.26.10"
  },
  "devDependencies": {
    "@dcloudio/uni-helper-json": "^1.0.5"
  }
}

Common Environment Issue Solutions

Permission Errors (Mac/Linux)

# Fix npm global installation permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Version Conflict Resolution

# Clear cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Specific Node Version Requirements

Constrain versions via the engines field:

{
  "engines": {
    "node": ">=14.0.0 <17.0.0",
    "npm": ">=6.0.0"
  }
}

Multi-Environment Management Tips

1. Use .npmrc for project-level settings:

   registry=https://registry.npmmirror.com
   sass_binary_site=https://npmmirror.com/mirrors/node-sass/
   

2. Handle cross-platform environment variables with cross-env:

   npm install cross-env --save-dev
   

   "scripts": {
     "build": "cross-env NODE_ENV=production uni build"
   }
   

Automated Deployment Configuration

CI/CD example (GitHub Actions):

name: Build Uni-app
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm install
      - run: npm run build:h5

Performance Optimization Suggestions

1. Use npm ci instead of npm install in CI/CD:

   npm ci --production  # Install production dependencies only
   

2. Install dependencies on demand:

   # Install only essential runtime dependencies
   npm install --omit=dev
   

3. Use pnpm as an npm alternative:

   npm install -g pnpm
   pnpm install  # Faster and saves disk space