Node.js+环境笔记

2024-01-01

1. NVM 安装与配置

1.1 NVM 简介

NVM (Node Version Manager) 是一个用于管理多个 Node.js 版本的工具，允许您在同一台机器上安装和切换不同版本的 Node.js。

主要优势：

  • 支持多版本 Node.js 并存

  • 快速切换 Node.js 版本

  • 项目级别版本管理

  • 简化版本升级和降级

1.2 安装 NVM

Linux/macOS 安装

1
2
3
4
5
# 使用 curl 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
​
# 或使用 wget 安装
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

更新环境变量

1
2
3
4
5
6
7
# 更新 bash 配置
source ~/.bashrc 
​
# 更新 zsh 配置（如果使用 zsh）
source ~/.zshrc
​
# 或者重启终端

验证安装

1
2
3
4
5
# 检查 NVM 版本
nvm --version
​
# 查看 NVM 帮助
nvm --help

1.3 Windows 安装

使用 nvm-windows

1
2
3
4
5
6
7
# 1. 从 GitHub 下载 nvm-windows
# https://github.com/coreybutler/nvm-windows/releases
​
# 2. 下载 nvm-setup.zip 并解压安装
​
# 3. 验证安装
nvm version

配置镜像源（可选）

1
2
3
4
5
# 设置 Node.js 下载镜像
nvm node_mirror https://npm.taobao.org/mirrors/node/
​
# 设置 NPM 下载镜像
nvm npm_mirror https://npm.taobao.org/mirrors/npm/

2. Node.js 版本管理

2.1 查看可用版本

查看远程版本

1
2
3
4
5
6
7
8
# 查看所有可用的 Node.js 版本
nvm list-remote
​
# 查看所有可用的 LTS 版本
nvm list-remote --lts
​
# 查看指定主版本的所有版本
nvm list-remote 18

查看本地已安装版本

1
2
3
4
5
6
7
8
# 查看本地安装的所有版本
nvm list
​
# 简化显示
nvm ls
​
# 查看当前使用的版本
nvm current

2.2 安装 Node.js

安装最新版本

1
2
3
4
5
6
7
8
# 安装最新版本
nvm install node
​
# 安装最新的 LTS 版本
nvm install --lts
​
# 安装最新的 LTS 版本并使用
nvm install --lts --reinstall-packages-from=current

安装指定版本

1
2
3
4
5
6
7
8
# 安装指定版本
nvm install 18.17.0

# 安装指定主版本的最新版本
nvm install 18

# 安装并立即使用
nvm install 16.20.0 --reinstall-packages-from=current

从 .nvmrc 文件安装

1
2
3
4
5
# 安装 .nvmrc 文件中指定的版本
nvm install

# 如果版本已安装，则直接使用
nvm use

2.3 切换 Node.js 版本

切换到指定版本

1
2
3
4
5
6
7
8
9
10
11
# 切换到指定版本
nvm use 18.17.0

# 切换到最新 LTS 版本
nvm use --lts

# 切换到最新版本
nvm use node

# 切换到系统默认版本
nvm use system

设置默认版本

1
2
3
4
5
6
7
8
# 设置默认 Node.js 版本
nvm alias default 18.17.0

# 设置默认为最新 LTS
nvm alias default lts/*

# 设置默认为最新版本
nvm alias default node

2.4 卸载 Node.js 版本

卸载指定版本

1
2
3
4
5
6
7
8
# 卸载指定版本
nvm uninstall 16.20.0

# 卸载多个版本
nvm uninstall 14.21.0 16.20.0

# 强制卸载（即使正在使用）
nvm uninstall 18.17.0 --force

3. 项目环境配置

3.1 .nvmrc 文件

创建 .nvmrc 文件

1
2
3
4
5
# 在项目根目录创建 .nvmrc 文件
echo "18.17.0" > .nvmrc

# 或者使用当前版本
node --version > .nvmrc

.nvmrc 文件示例

1
2
3
4
5
6
7
8
# .nvmrc 内容示例
18.17.0

# 或者使用别名
lts/hydrogen

# 或者使用主版本号
18

使用 .nvmrc 文件

1
2
3
4
5
6
7
8
9
10
11
# 进入项目目录
cd /path/to/project

# 安装并使用 .nvmrc 指定的版本
nvm install

# 如果版本已安装，直接切换
nvm use

# 检查当前版本是否符合要求
nvm which current

3.2 自动版本切换

Bash 自动切换

1
2
3
4
5
6
7
8
9
10
11
# 在 ~/.bashrc 或 ~/.zshrc 中添加
cdnvm() {
    cd "$@";
    if [[ -f .nvmrc && -r .nvmrc ]]; then
        nvm use
    elif [[ $(nvm version) != $(nvm version default)  ]]; then
        echo "Reverting to nvm default version"
        nvm use default
    fi
}
alias cd="cdnvm"

Zsh 自动切换（使用 zsh-nvm 插件）

1
2
3
4
5
6
7
8
# 安装 oh-my-zsh 插件
git clone https://github.com/lukechilds/zsh-nvm ~/.oh-my-zsh/custom/plugins/zsh-nvm

# 在 ~/.zshrc 中启用插件
plugins=(... zsh-nvm)

# 重载配置
source ~/.zshrc

3.3 项目级包管理器配置

配置 NPM 镜像源

1
2
3
4
5
6
7
8
9
10
11
# 临时使用淘宝镜像
npm install --registry=https://registry.npm.taobao.org

# 全局设置淘宝镜像
npm config set registry https://registry.npm.taobao.org

# 查看当前镜像源
npm config get registry

# 恢复官方镜像源
npm config set registry https://registry.npmjs.org

使用 .npmrc 文件

1
2
3
4
5
6
7
8
9
# 项目级 .npmrc 文件
echo "registry=https://registry.npm.taobao.org" > .npmrc

# 添加其他配置
cat << EOF > .npmrc
registry=https://registry.npm.taobao.org
save-exact=true
package-lock=true
EOF

4. NPM 包管理

4.1 基本包管理命令

初始化项目

1
2
3
4
5
6
7
8
# 初始化新项目
npm init

# 快速初始化（使用默认值）
npm init -y

# 使用指定模板初始化
npm init react-app my-app

安装依赖包

1
2
3
4
5
6
7
8
9
10
11
12
13
# 安装生产依赖
npm install package-name
npm i package-name

# 安装开发依赖
npm install --save-dev package-name
npm i -D package-name

# 全局安装
npm install -g package-name

# 安装指定版本
npm install package-name@1.2.3

更新和卸载

1
2
3
4
5
6
7
8
9
10
11
# 更新所有包
npm update

# 更新指定包
npm update package-name

# 卸载包
npm uninstall package-name

# 卸载全局包
npm uninstall -g package-name

4.2 锁定文件管理

package-lock.json

1
2
3
4
5
6
7
8
9
10
11
# 生成 package-lock.json
npm install

# 根据 package-lock.json 安装
npm ci

# 忽略 package-lock.json
npm install --no-package-lock

# 更新 package-lock.json
npm install --package-lock-only

版本控制最佳实践

1
2
3
4
5
6
7
8
9
10
11
# .gitignore 示例
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# 应该提交的文件
package.json          # ✓ 提交
package-lock.json     # ✓ 提交
.nvmrc               # ✓ 提交
.npmrc               # ✓ 提交（项目级）

4.3 脚本管理

package.json 脚本示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "name": "my-project",
  "version": "1.0.0",
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=8.0.0"
  },
  "scripts": {
    "dev": "node server.js",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src/",
    "start": "npm run build && node dist/server.js",
    "clean": "rm -rf dist node_modules",
    "setup": "npm install && npm run build"
  },
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "webpack": "^5.0.0",
    "jest": "^29.0.0"
  }
}

运行脚本

1
2
3
4
5
6
7
8
9
10
# 运行预定义脚本
npm run dev
npm run build
npm test

# 运行多个脚本
npm run clean && npm run setup

# 传递参数给脚本
npm run test -- --watch

5. 常见问题解决

5.1 权限问题

解决全局安装权限问题

1
2
3
4
5
6
7
8
9
10
# 方法1：改变 npm 默认目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# 添加到环境变量（在 ~/.bashrc 或 ~/.zshrc 中）
export PATH=~/.npm-global/bin:$PATH

# 方法2：使用 nvm（推荐）
# nvm 会自动处理权限问题
nvm install node

清理权限问题

1
2
3
4
5
6
# 重置 npm 权限
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# 或者完全重新安装 Node.js
nvm uninstall node
nvm install node

5.2 版本冲突问题

解决版本不兼容

1
2
3
4
5
6
7
8
9
# 检查项目要求的 Node.js 版本
cat package.json | grep engines

# 切换到兼容版本
nvm use 18.17.0

# 重新安装依赖
rm -rf node_modules package-lock.json
npm install

处理多项目版本需求

1
2
3
4
5
6
7
8
9
# 项目A使用 Node.js 16
cd /path/to/projectA
echo "16.20.0" > .nvmrc
nvm use

# 项目B使用 Node.js 18
cd /path/to/projectB
echo "18.17.0" > .nvmrc
nvm use

5.3 缓存和网络问题

清理缓存

1
2
3
4
5
6
7
8
# 清理 npm 缓存
npm cache clean --force

# 清理 nvm 缓存
nvm cache clear

# 验证缓存
npm cache verify

网络问题解决

1
2
3
4
5
6
7
8
9
# 使用国内镜像源
npm config set registry https://registry.npm.taobao.org

# 或使用 cnpm
npm install -g cnpm --registry=https://registry.npm.taobao.org
cnpm install

# 临时使用代理
npm install --proxy http://proxy.company.com:8080

5.4 NVM 常见问题

NVM 命令找不到

1
2
3
4
5
6
7
8
9
10
# 检查 NVM 是否正确安装
ls -la ~/.nvm

# 手动加载 NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 永久修复（添加到 ~/.bashrc）
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrc

版本切换失败

1
2
3
4
5
6
7
8
9
# 检查当前版本
nvm current

# 强制重新安装
nvm uninstall 18.17.0
nvm install 18.17.0

# 重建符号链接
nvm reinstall-packages 18.17.0

6. 最佳实践

6.1 项目配置最佳实践

标准项目结构

1
2
3
4
5
6
7
8
9
10
my-project/
├── package.json          # 项目依赖和脚本
├── package-lock.json      # 锁定依赖版本
├── .nvmrc                # Node.js 版本
├── .npmrc                # NPM 配置
├── .gitignore            # Git 忽略文件
├── README.md             # 项目说明
├── src/                  # 源代码
├── tests/                # 测试文件
└── docs/                 # 文档

环境检查脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
#!/bin/bash
# check-env.sh

echo "🔍 检查开发环境..."

# 检查 Node.js 版本
if [ -f .nvmrc ]; then
    REQUIRED_NODE=$(cat .nvmrc)
    CURRENT_NODE=$(node --version | sed 's/v//')
    
    if [ "$CURRENT_NODE" != "$REQUIRED_NODE" ]; then
        echo "⚠️  Node.js 版本不匹配!"
        echo "   需要: $REQUIRED_NODE"
        echo "   当前: $CURRENT_NODE"
        echo "   运行: nvm use"
        exit 1
    else
        echo "✅ Node.js 版本正确: $CURRENT_NODE"
    fi
fi

# 检查依赖是否安装
if [ ! -d "node_modules" ]; then
    echo "⚠️  依赖未安装，运行: npm install"
    exit 1
else
    echo "✅ 依赖已安装"
fi

echo "🎉 环境检查通过!"

6.2 团队协作最佳实践

统一开发环境

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "name": "team-project",
  "engines": {
    "node": ">=18.0.0 <19.0.0",
    "npm": ">=8.0.0"
  },
  "scripts": {
    "preinstall": "node scripts/check-node-version.js",
    "postinstall": "echo '✅ 依赖安装完成'",
    "dev": "node scripts/check-env.js && npm run start:dev",
    "setup": "nvm use && npm install"
  }
}

Git Hooks 配置

1
2
3
4
5
6
7
8
9
10
11
12
# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# 检查 Node.js 版本
if [ -f .nvmrc ]; then
  nvm use
fi

# 运行测试和检查
npm run lint
npm run test

6.3 性能优化

NPM 安装优化

1
2
3
4
5
6
7
8
9
10
11
12
# 使用 npm ci 进行快速安装（生产环境）
npm ci

# 并行安装依赖
npm install --prefer-offline

# 使用本地缓存
npm config set cache /path/to/cache

# 禁用不必要的功能
npm config set audit false
npm config set fund false

依赖管理优化

1
2
3
4
5
6
7
8
9
{
  "scripts": {
    "audit": "npm audit",
    "audit-fix": "npm audit fix",
    "outdated": "npm outdated",
    "update-deps": "npm update && npm audit fix",
    "clean-install": "rm -rf node_modules package-lock.json && npm install"
  }
}

6.4 多环境管理

环境配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# .env.development
NODE_ENV=development
API_URL=http://localhost:3000
DEBUG=true

# .env.production
NODE_ENV=production
API_URL=https://api.production.com
DEBUG=false

# .env.test
NODE_ENV=test
API_URL=http://localhost:3001
DEBUG=false

环境切换脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#!/bin/bash
# switch-env.sh

ENV=${1:-development}

case $ENV in
  "dev"|"development")
    cp .env.development .env
    echo "切换到开发环境"
    ;;
  "prod"|"production")
    cp .env.production .env
    echo "切换到生产环境"
    ;;
  "test")
    cp .env.test .env
    echo "切换到测试环境"
    ;;
  *)
    echo "使用方法: $0 [dev|prod|test]"
    exit 1
    ;;
esac

echo "当前环境: $ENV"
echo "Node.js 版本: $(node --version)"
echo "NPM 版本: $(npm --version)"

6.5 自动化脚本

项目初始化脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
#!/bin/bash
# setup-project.sh

echo "🚀 初始化项目..."

# 检查并安装 NVM
if ! command -v nvm &> /dev/null; then
    echo "安装 NVM..."
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
    source ~/.bashrc
fi

# 使用项目指定的 Node.js 版本
if [ -f .nvmrc ]; then
    echo "使用 .nvmrc 指定的 Node.js 版本..."
    nvm install
    nvm use
else
    echo "使用最新 LTS 版本..."
    nvm install --lts
    nvm use --lts
fi

# 安装依赖
echo "安装项目依赖..."
npm install

# 运行初始化脚本
if npm run setup &> /dev/null; then
    npm run setup
fi

echo "✅ 项目初始化完成!"
echo "运行 'npm run dev' 启动开发服务器"

版本升级脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
#!/bin/bash
# upgrade-node.sh

CURRENT_VERSION=$(node --version)
echo "当前 Node.js 版本: $CURRENT_VERSION"

# 查看可用的 LTS 版本
echo "可用的 LTS 版本:"
nvm list-remote --lts

echo "是否升级到最新 LTS 版本? (y/n)"
read -r response

if [[ "$response" =~ ^([yY][eE][sS]|[yY])$ ]]; then
    echo "升级中..."
    
    # 重新安装包到新版本
    nvm install --lts --reinstall-packages-from=current
    
    # 更新 .nvmrc 文件
    nvm version lts/* | sed 's/v//' > .nvmrc
    
    echo "✅ 升级完成!"
    echo "新版本: $(node --version)"
    echo "已更新 .nvmrc 文件"
else
    echo "取消升级"
fi

通过这个完整的 Node.js 版本管理指南，您可以高效地管理多个 Node.js 版本，确保项目的兼容性和团队协作的一致性。

RELATED POSTS
CMake交叉编译
1. CMake 基础概念1.1 CMake 工作流程CMake 构建过程分为两个主要阶段： 配置阶段 (Configure)1cmake .. -DBUILD_32BIT=ON -DTARGET_TYPE=exe 配置阶段的作用： 读取并...
cmake, 交叉编译, buildroot Jan 01 18 min
Docker环境搭建笔记
1. Docker 安装1.1 快速安装一键安装脚本12# 使用阿里云镜像安装curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun 启动Docker服务1234...
Linux, docker Jan 01 6 min
Linux系统笔记
1. 文件和目录操作1.1 基本文件操作查看文件和目录12345678910# 查看当前目录内容ls # 基本列表ls -l # 详细信息ls -la # 包含隐藏文件ls -lh # 人性化大小显示​# 查看目录结构tree # 树状显示...
Linux Jan 01 10 min
Nginx+安装与配置
1. Nginx 安装1.1 安装前准备创建工作目录1mkdir nginx &amp;&amp; cd nginx 安装必要工具12345678# 安装wget下载工具yum -y install wget​# 安装构建工具yum -y ...
Nginx, 代理 Jan 01 2 min
Ubuntu+Windows共享文件夹
一、SSHFS文件共享方案1.1 概述基于SSH协议的SSHFS挂载方案，实现Ubuntu和Windows之间的安全文件共享。适合个人开发环境和需要加密传输的场景。 1.2 软件依赖关系依赖架构12Windows端：应用程序 → SSHFS...
Linux, shared Jan 01 4 min
WSL+SSH连接笔记
1. WSL架构理解WSL（Windows Subsystem for Linux）是微软开发的兼容层，允许在Windows上原生运行Linux环境： WSL 2架构：基于Hyper-V轻量级虚拟机运行完整Linux内核，相比传统虚拟机启动...
Linux, ssh, wsl Jan 01 1 min
View More Posts