Node.js 安装指南（Mac 版本）

第一章：准备工作与环境检查

1.1 确认系统要求

在开始安装 Node.js 之前，首先需要确认您的 Mac 系统是否符合要求：

系统版本要求：

• macOS 10.10 (Yosemite) 或更高版本
• 推荐使用 macOS 10.15 (Catalina) 或更新版本
• 同时支持 Intel 和 Apple Silicon (M1/M2) 芯片

检查您的 macOS 版本：

1. 点击屏幕左上角的 Apple 菜单
2. 选择"关于本机"
3. 查看显示的版本信息

通过终端检查：

bash

sw_vers

输出示例：

text

ProductName: macOS ProductVersion: 12.6.1 BuildVersion: 21G217

1.2 检查现有 Node.js 安装

在安装新版本之前，检查系统是否已安装 Node.js：

bash

# 检查 Node.js 版本 node --version # 检查 npm 版本 npm --version # 检查 Node.js 安装路径 which node # 检查所有相关的 Node.js 可执行文件 whereis node

如果系统返回版本信息，说明已有 Node.js 安装。您需要决定是保留现有版本、升级还是完全重新安装。

1.3 备份重要数据

如果您已经在开发 Node.js 项目，建议备份：

1. 项目文件：复制整个项目目录到安全位置
2. 全局 npm 包：列出并记录已安装的全局包

bash

npm list -g --depth=0

1. npm 配置：备份 npm 配置文件

bash

cp ~/.npmrc ~/.npmrc.backup

1.4 清理可能的旧版本

如果之前通过其他方式安装过 Node.js，建议先清理：

检查并移除通过 Homebrew 安装的 Node.js：

bash

brew uninstall node brew cleanup

检查并移除通过 pkg 安装的 Node.js：

bash

sudo rm -rf /usr/local/{bin/{node,npm},lib/node_modules/npm,lib/node,share/man/*/node.*}

第二章：安装方法概述与选择

2.1 主要安装方法比较

方法一：官方安装包

• 优点：官方提供，稳定性高，适合新手
• 缺点：版本切换不够灵活

方法二：Homebrew

• 优点：包管理器统一管理，更新方便
• 缺点：可能不是最新版本

方法三：Node Version Manager (nvm)

• 优点：多版本管理，灵活切换
• 缺点：学习曲线稍陡

方法四：从源码编译

• 优点：完全控制编译选项
• 缺点：耗时，适合高级用户

2.2 推荐安装方案

新手用户：推荐使用官方安装包
普通开发者：推荐使用 nvm
高级用户：可根据需求选择 Homebrew 或源码编译

第三章：方法一 - 使用官方安装包

3.1 下载官方安装包

1. 访问 Node.js 官网
   打开浏览器，访问 https://nodejs.org/
2. 选择合适版本
   • LTS (Long Term Support)：长期支持版，稳定性高，推荐生产环境使用
   • Current：最新特性版，包含最新功能，适合测试和学习
3. 下载安装包
   • 网站会自动检测您的操作系统，提供对应的下载链接
   • 对于 Apple Silicon Mac，会下载 ARM64 版本
   • 对于 Intel Mac，会下载 x64 版本
4. 验证下载文件
   下载完成后，检查文件完整性：bash# 检查文件大小 ls -lh ~/Downloads/node-*.pkg # 可选：验证 SHA256 校验和 shasum -a 256 ~/Downloads/node-*.pkg

3.2 安装过程详解

1. 打开安装包
   • 在下载文件夹中找到 .pkg 文件
   • 双击打开安装程序
2. 安装向导步骤
   • 欢迎界面：阅读介绍信息，点击"继续"
   • 许可协议：仔细阅读协议，点击"继续"然后"同意"
   • 安装目标：选择安装磁盘（通常默认即可）
   • 安装类型：点击"安装"开始安装过程
3. 认证过程
   • 系统会要求输入管理员密码
   • 输入密码后点击"安装软件"
4. 安装完成
   • 等待进度条完成
   • 看到"安装成功"提示后点击"关闭"

3.3 验证安装

安装完成后，验证 Node.js 是否正确安装：

bash

# 打开终端（可通过 Spotlight 搜索"终端"或 Finder -> 应用程序 -> 实用工具 -> 终端） # 检查 Node.js 版本 node --version # 检查 npm 版本 npm --version # 检查安装路径 which node which npm # 运行 Node.js REPL 环境测试 node > console.log("Node.js 安装成功！") > .exit

预期输出示例：

text

$ node --version v18.12.1 $ npm --version 8.19.2 $ which node /usr/local/bin/node

第四章：方法二 - 使用 Homebrew 安装

4.1 安装 Homebrew

如果尚未安装 Homebrew，首先需要安装：

bash

# 安装 Homebrew /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装过程详解：

1. 下载安装脚本
   • 终端会下载安装脚本并显示安装说明
   • 按回车键继续安装
2. 安装 Xcode Command Line Tools
   • 如果未安装，会自动触发安装
   • 这可能需要较长时间，请耐心等待
3. 设置环境变量
   安装完成后，按照提示将 Homebrew 添加到 PATH：对于 Intel Mac：bashecho 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile eval "$(/usr/local/bin/brew shellenv)"对于 Apple Silicon Mac：bashecho 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)"
4. 验证 Homebrew 安装bashbrew --version brew doctor

4.2 使用 Homebrew 安装 Node.js

bash

# 更新 Homebrew 包列表 brew update # 搜索可用的 Node.js 版本 brew search node # 安装 Node.js（这会安装最新稳定版） brew install node # 或者安装特定版本 brew install node@18

4.3 配置环境变量

如果安装了特定版本，可能需要手动链接：

bash

# 查看已安装的 Node.js 版本 brew list --versions | grep node # 如果安装了 node@18，需要链接 brew link node@18 --force --overwrite

4.4 验证安装

bash

# 验证安装 node --version npm --version # 检查 Homebrew 安装信息 brew info node

第五章：方法三 - 使用 Node Version Manager (nvm)

5.1 安装 nvm

nvm 是 Node.js 版本管理工具，允许安装和切换多个 Node.js 版本。

安装方法：

bash

# 使用安装脚本（推荐） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 或者使用 Homebrew 安装 nvm brew install nvm

手动安装步骤（如果上述方法失败）：

1. 创建 nvm 目录bashmkdir -p ~/.nvm
2. 克隆 nvm 仓库bashgit clone https://github.com/nvm-sh/nvm.git ~/.nvm cd ~/.nvm git checkout v0.39.0

5.2 配置 Shell 环境

根据使用的 Shell 类型配置环境变量：

对于 Bash：

bash

# 编辑 ~/.bash_profile 或 ~/.bashrc echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bash_profile echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm' >> ~/.bash_profile echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion' >> ~/.bash_profile

对于 Zsh：

bash

# 编辑 ~/.zshrc echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm' >> ~/.zshrc echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion' >> ~/.zshrc

应用配置：

bash

# 重新加载配置文件 source ~/.bash_profile # 对于 Bash source ~/.zshrc # 对于 Zsh # 或者重新启动终端

5.3 验证 nvm 安装

bash

# 检查 nvm 版本 nvm --version # 查看 nvm 帮助 nvm --help

5.4 使用 nvm 安装和管理 Node.js

查看可用的 Node.js 版本：

bash

# 查看所有可用版本 nvm ls-remote # 查看所有 LTS 版本 nvm ls-remote --lts # 查看可安装的版本 nvm list available

安装 Node.js 版本：

bash

# 安装最新稳定版 nvm install stable # 安装最新 LTS 版本 nvm install --lts # 安装特定版本 nvm install 18.12.1 # 安装特定大版本的最新版 nvm install 16

管理已安装的版本：

bash

# 查看已安装的版本 nvm ls # 使用特定版本 nvm use 18.12.1 # 设置默认版本 nvm alias default 18.12.1 # 查看当前使用的版本 nvm current

其他有用命令：

bash

# 在当前版本运行命令 nvm run 18.12.1 app.js # 查看某个版本的安装路径 nvm which 18.12.1 # 卸载特定版本 nvm uninstall 14.17.0

第六章：安装后配置与优化

6.1 配置 npm

检查 npm 配置：

bash

npm config list npm config ls -l

设置全局配置：

bash

# 设置注册表镜像（如果需要） npm config set registry https://registry.npmjs.org/ # 设置包安装位置 npm config set prefix ~/.npm-global # 将全局 bin 目录添加到 PATH echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc # 设置 npm 保存精确版本 npm config set save-exact true # 设置 npm 安装时保存前缀 npm config set save-prefix="~"

6.2 安装常用全局工具

bash

# 包更新检查工具 npm install -g npm-check-updates # Node.js 进程管理器 npm install -g pm2 # 开发工具 npm install -g nodemon npm install -g http-server npm install -g live-server # 脚手架工具 npm install -g create-react-app npm install -g @vue/cli npm install -g express-generator # 代码质量工具 npm install -g eslint npm install -g prettier # TypeScript npm install -g typescript ts-node # 验证安装 npm list -g --depth=0

6.3 配置项目默认设置

创建 ~/.npmrc 文件设置默认配置：

ini

# ~/.npmrc init-author-name=您的姓名 init-author-email=您的邮箱 init-author-url=您的网站 init-license=MIT save=true save-exact=true package-lock=true fund=false audit=false

6.4 性能优化配置

调整 Node.js 内存限制：

bash

# 查看当前内存使用 node -e "console.log(process.memoryUsage())" # 设置环境变量增加内存限制 echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.zshrc

配置 npm 缓存：

bash

# 查看缓存位置 npm config get cache # 清理缓存 npm cache clean --force # 验证缓存完整性 npm cache verify

第七章：创建和运行第一个 Node.js 应用

7.1 创建项目目录

bash

# 创建项目目录 mkdir my-first-node-app cd my-first-node-app # 初始化 npm 项目 npm init -y

7.2 创建简单的 Node.js 应用

创建 app.js 文件：

javascript

// app.js const http = require('http'); const hostname = '127.0.0.1'; const port = 3000; const server = http.createServer((req, res) => { res.statusCode = 200; res.setHeader('Content-Type', 'text/plain'); res.end('Hello, World! 欢迎来到 Node.js 世界！\n'); }); server.listen(port, hostname, () => { console.log(`服务器运行在 http://${hostname}:${port}/`); console.log(`进程 ID: ${process.pid}`); console.log(`Node.js 版本: ${process.version}`); });

7.3 运行应用

bash

# 运行应用 node app.js # 在浏览器中访问 http://127.0.0.1:3000 # 或者使用 curl 测试 curl http://127.0.0.1:3000

7.4 添加依赖和脚本

安装 Express 框架：

bash

npm install express

创建使用 Express 的版本 app-express.js：

javascript

// app-express.js const express = require('express'); const app = express(); const port = 3000; app.get('/', (req, res) => { res.send(` <h1>Hello, World!</h1> <p>欢迎来到 Node.js + Express 世界！</p> <ul> <li>Node.js 版本: ${process.version}</li> <li>平台: ${process.platform}</li> <li>架构: ${process.arch}</li> </ul> `); }); app.listen(port, () => { console.log(`Express 应用运行在 http://localhost:${port}`); });

更新 package.json 中的脚本部分：

json

{ "scripts": { "start": "node app.js", "dev": "node app-express.js", "test": "echo \"Error: no test specified\" && exit 1" } }

现在可以使用 npm start 或 npm run dev 运行应用。

第八章：故障排除和常见问题

8.1 权限问题

npm EACCES 错误解决方案：

方法一：使用 Node.js 内置解决方案

bash

# 重新安装 npm 并设置正确权限 npm install -g npm@latest

方法二：更改 npm 默认目录

bash

mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc

方法三：使用 sudo（不推荐）

bash

sudo npm install -g package-name

8.2 版本冲突问题

解决 Node.js 版本冲突：

bash

# 检查所有 Node.js 安装 which -a node which -a npm # 如果使用 nvm，确保正确设置了默认版本 nvm alias default 18.12.1 nvm use default

8.3 端口被占用

bash

# 查找占用端口的进程 lsof -i :3000 # 终止进程 kill -9 <PID> # 或者使用不同的端口 node app.js --port 8080

8.4 内存不足问题

bash

# 增加 Node.js 内存限制 export NODE_OPTIONS="--max-old-space-size=4096" # 永久设置 echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.zshrc

8.5 Homebrew 相关问题

解决 Homebrew 安装问题：

bash

# 重置 Homebrew brew doctor brew update-reset # 清理 Homebrew brew cleanup brew autoremove # 重新安装 Node.js brew uninstall node brew install node

第九章：开发环境配置建议

9.1 代码编辑器配置

Visual Studio Code 推荐扩展：

• ESLint
• Prettier - Code formatter
• npm
• npm Intellisense
• Path Intellisense
• Code Runner
• Thunder Client (API 测试)

配置 VS Code 设置：

json

{ "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll.eslint": true }, "emmet.includeLanguages": { "javascript": "javascriptreact" } }

9.2 版本控制配置

创建 .gitignore 文件：

text

# 依赖目录 node_modules/ npm-debug.log* yarn-debug.log* yarn-error.log* # 环境变量 .env .env.local .env.development.local .env.test.local .env.production.local # 日志 logs *.log # 运行时数据 pids *.pid *.seed *.pid.lock # 覆盖目录 coverage/ .nyc_output # 缓存 .npm .eslintcache

9.3 调试配置

创建 VS Code 调试配置 .vscode/launch.json：

json

{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "启动程序", "skipFiles": ["<node_internals>/**"], "program": "${workspaceFolder}/app.js", "env": { "NODE_ENV": "development" } } ] }

第十章：维护和更新

10.1 更新 Node.js

使用 nvm 更新：

bash

# 安装新版本 nvm install node --reinstall-packages-from=node # 或者安装最新 LTS nvm install --lts --reinstall-packages-from=default # 设置新版本为默认 nvm alias default node

使用 Homebrew 更新：

bash

brew update brew upgrade node

使用官方安装包更新：
下载新版本安装包，运行安装程序，它会自动替换旧版本。

10.2 更新 npm

bash

# 更新 npm 到最新版本 npm install -g npm@latest # 检查更新 npm outdated -g # 更新所有全局包 npm update -g

10.3 定期维护任务

bash

# 清理 npm 缓存 npm cache clean --force # 检查安全漏洞 npm audit # 修复漏洞 npm audit fix # 更新项目依赖 npx npm-check-updates -u npm install

第十一章：进阶主题

11.1 使用不同的包管理器

Yarn 安装：

bash

# 使用 Homebrew 安装 brew install yarn # 或者使用 npm 安装 npm install -g yarn # 基本使用 yarn init yarn add package-name yarn install

pnpm 安装：

bash

# 使用 Homebrew 安装 brew install pnpm # 或者使用 npm 安装 npm install -g pnpm # 基本使用 pnpm init pnpm add package-name pnpm install

11.2 配置多环境

设置环境特定的配置：

javascript

// config.js const environments = { development: { port: 3000, database: 'mongodb://localhost:27017/dev' }, production: { port: process.env.PORT || 80, database: process.env.MONGODB_URI } }; const environment = process.env.NODE_ENV || 'development'; module.exports = environments[environment];

11.3 性能监控

安装和使用监控工具：

bash

# 安装监控工具 npm install -g clinic npm install -g 0x # 使用 clinic 分析性能 clinic doctor -- node app.js # 生成火焰图 0x app.js

第十二章：总结

12.1 安装方法回顾

通过本指南，您已经学会了在 Mac 上安装 Node.js 的多种方法：

1. 官方安装包：最适合新手，简单直接
2. Homebrew：适合习惯使用包管理器的用户
3. nvm：适合需要多版本管理的开发者

12.2 最佳实践建议

1. 生产环境：使用 LTS 版本
2. 开发环境：根据项目需求选择合适的版本
3. 学习环境：可以尝试 Current 版本体验最新特性
4. 团队协作：统一 Node.js 版本和包管理器

12.3 后续学习路径

1. 深入学习 Node.js 核心模块
2. 学习 Express 等流行框架
3. 掌握数据库集成
4. 学习测试和部署
5. 探索 TypeScript

12.4 获取帮助

• 官方文档：https://nodejs.org/docs/
• npm 文档：https://docs.npmjs.com/
• Stack Overflow：搜索相关问题
• GitHub：查看项目 issue 和讨论