本文档详细介绍了在 macOS 系统上安装和配置 Node.js 的完整流程。内容涵盖系统环境检查、三种主流安装方式（官方安装包、Homebrew、nvm）的具体步骤及对比、npm 配置优化、首个 Node.js 应用的创建与运行，以及常见故障排除方法。旨在帮助新手及开发者快速搭建稳定的 Node.js 开发环境。
在开始安装 Node.js 之前，首先需要确认您的 Mac 系统是否符合要求：
系统版本要求：
检查您的 macOS 版本：
通过终端检查：
sw_vers
输出示例：
ProductName: macOS ProductVersion: 12.6.1 BuildVersion: 21G217
在安装新版本之前，检查系统是否已安装 Node.js：
# 检查 Node.js 版本
node --version
# 检查 npm 版本
npm --version
# 检查 Node.js 安装路径
which node
# 检查所有相关的 Node.js 可执行文件
whereis node
如果系统返回版本信息，说明已有 Node.js 安装。您需要决定是保留现有版本、升级还是完全重新安装。
如果您已经在开发 Node.js 项目，建议备份：
npm list -g --depth=0
cp ~/.npmrc ~/.npmrc.backup
如果之前通过其他方式安装过 Node.js，建议先清理：
检查并移除通过 Homebrew 安装的 Node.js：
brew uninstall node
brew cleanup
检查并移除通过 pkg 安装的 Node.js：
sudo rm -rf /usr/local/{bin/{node,npm},lib/node_modules/npm,lib/node,share/man/*/node.*}
方法一：官方安装包
方法二：Homebrew
方法三：Node Version Manager (nvm)
方法四：从源码编译
新手用户：推荐使用官方安装包 普通开发者：推荐使用 nvm 高级用户：可根据需求选择 Homebrew 或源码编译
# 检查文件大小
ls -lh ~/Downloads/node-*.pkg
# 可选：验证 SHA256 校验和
shasum -a 256 ~/Downloads/node-*.pkg
.pkg 文件安装完成后，验证 Node.js 是否正确安装：
# 打开终端（可通过 Spotlight 搜索'终端'或 Finder -> 应用程序 -> 实用工具 -> 终端）
# 检查 Node.js 版本
node --version
# 检查 npm 版本
npm --version
# 检查安装路径
which node
which npm
# 运行 Node.js REPL 环境测试
node
> console.log("Node.js 安装成功！")
> .exit
预期输出示例：
$ node --version
v18.12.1
$ npm --version
8.19.2
$ which node
/usr/local/bin/node
如果尚未安装 Homebrew，首先需要安装：
# 安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装过程详解：
对于 Intel Mac：
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"
对于 Apple Silicon Mac：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew --version
brew doctor
# 更新 Homebrew 包列表
brew update
# 搜索可用的 Node.js 版本
brew search node
# 安装 Node.js（这会安装最新稳定版）
brew install node
# 或者安装特定版本
brew install node@18
如果安装了特定版本，可能需要手动链接：
# 查看已安装的 Node.js 版本
brew list --versions | grep node
# 如果安装了 node@18，需要链接
brew link node@18 --force --overwrite
# 验证安装
node --version
npm --version
# 检查 Homebrew 安装信息
brew info node
nvm 是 Node.js 版本管理工具，允许安装和切换多个 Node.js 版本。
安装方法：
# 使用安装脚本（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 或者使用 Homebrew 安装
brew install nvm
手动安装步骤（如果上述方法失败）：
mkdir -p ~/.nvm
git clone https://github.com/nvm-sh/nvm.git ~/.nvm
cd ~/.nvm
git checkout v0.39.0
根据使用的 Shell 类型配置环境变量：
对于 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：
# 编辑 ~/.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
应用配置：
# 重新加载配置文件
source ~/.bash_profile # 对于 Bash
source ~/.zshrc # 对于 Zsh
# 或者重新启动终端
# 检查 nvm 版本
nvm --version
# 查看 nvm 帮助
nvm --help
查看可用的 Node.js 版本：
# 查看所有可用版本
nvm ls-remote
# 查看所有 LTS 版本
nvm ls-remote --lts
# 查看可安装的版本
nvm list available
安装 Node.js 版本：
# 安装最新稳定版
nvm install stable
# 安装最新 LTS 版本
nvm install --lts
# 安装特定版本
nvm install 18.12.1
# 安装特定大版本的最新版
nvm install 16
管理已安装的版本：
# 查看已安装的版本
nvm ls
# 使用特定版本
nvm use 18.12.1
# 设置默认版本
nvm alias default 18.12.1
# 查看当前使用的版本
nvm current
其他有用命令：
# 在当前版本运行命令
nvm run 18.12.1 app.js
# 查看某个版本的安装路径
nvm which 18.12.1
# 卸载特定版本
nvm uninstall 14.17.0
检查 npm 配置：
npm config list
npm config ls -l
设置全局配置：
# 设置注册表镜像（如果需要）
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="~"
# 包更新检查工具
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
创建 ~/.npmrc 文件设置默认配置：
# ~/.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
调整 Node.js 内存限制：
# 查看当前内存使用
node -e "console.log(process.memoryUsage())"
# 设置环境变量增加内存限制
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.zshrc
配置 npm 缓存：
# 查看缓存位置
npm config get cache
# 清理缓存
npm cache clean --force
# 验证缓存完整性
npm cache verify
# 创建项目目录
mkdir my-first-node-app
cd my-first-node-app
# 初始化 npm 项目
npm init -y
创建 app.js 文件：
// 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}`);
});
# 运行应用
node app.js
# 在浏览器中访问 http://127.0.0.1:3000
# 或者使用 curl 测试
curl http://127.0.0.1:3000
安装 Express 框架：
npm install express
创建使用 Express 的版本 app-express.js：
// 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 中的脚本部分：
{
"scripts": {
"start": "node app.js",
"dev": "node app-express.js",
"test": "echo \"Error: no test specified\" && exit 1"
}
}
现在可以使用 npm start 或 npm run dev 运行应用。
npm EACCES 错误解决方案：
方法一：使用 Node.js 内置解决方案
# 重新安装 npm 并设置正确权限
npm install -g npm@latest
方法二：更改 npm 默认目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
方法三：使用 sudo（不推荐）
sudo npm install -g package-name
解决 Node.js 版本冲突：
# 检查所有 Node.js 安装
which -a node
which -a npm
# 如果使用 nvm，确保正确设置了默认版本
nvm alias default 18.12.1
nvm use default
# 查找占用端口的进程
lsof -i :3000
# 终止进程
kill -9 <PID>
# 或者使用不同的端口
node app.js --port 8080
# 增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"
# 永久设置
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.zshrc
解决 Homebrew 安装问题：
# 重置 Homebrew
brew doctor
brew update-reset
# 清理 Homebrew
brew cleanup
brew autoremove
# 重新安装 Node.js
brew uninstall node
brew install node
Visual Studio Code 推荐扩展：
配置 VS Code 设置：
{
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"emmet.includeLanguages": {
"javascript": "javascriptreact"
}
}
创建 .gitignore 文件：
# 依赖目录
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
创建 VS Code 调试配置 .vscode/launch.json：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "启动程序",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/app.js",
"env": {
"NODE_ENV": "development"
}
}
]
}
使用 nvm 更新：
# 安装新版本
nvm install node --reinstall-packages-from=node
# 或者安装最新 LTS
nvm install --lts --reinstall-packages-from=default
# 设置新版本为默认
nvm alias default node
使用 Homebrew 更新：
brew update
brew upgrade node
使用官方安装包更新： 下载新版本安装包，运行安装程序，它会自动替换旧版本。
# 更新 npm 到最新版本
npm install -g npm@latest
# 检查更新
npm outdated -g
# 更新所有全局包
npm update -g
# 清理 npm 缓存
npm cache clean --force
# 检查安全漏洞
npm audit
# 修复漏洞
npm audit fix
# 更新项目依赖
npx npm-check-updates -u
npm install
Yarn 安装：
# 使用 Homebrew 安装
brew install yarn
# 或者使用 npm 安装
npm install -g yarn
# 基本使用
yarn init
yarn add package-name
yarn install
pnpm 安装：
# 使用 Homebrew 安装
brew install pnpm
# 或者使用 npm 安装
npm install -g pnpm
# 基本使用
pnpm init
pnpm add package-name
pnpm install
设置环境特定的配置：
// 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];
安装和使用监控工具：
# 安装监控工具
npm install -g clinic
npm install -g 0x
# 使用 clinic 分析性能
clinic doctor -- node app.js
# 生成火焰图
0x app.js
通过本指南，您已经学会了在 Mac 上安装 Node.js 的多种方法：
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online