Node.js 是跨平台 JavaScript 运行时,npm 是随 Node.js 一起安装的包管理工具。本文介绍环境安装、项目初始化、依赖管理、版本规则、脚本、镜像配置和常见故障排查。
一、Node.js 与 npm 的关系
- Node.js:让 JavaScript 可以在浏览器之外运行,常用于 Web 服务、命令行工具和前端工程化。
- npm:Node Package Manager,用于安装、更新、删除和发布 JavaScript 包,也负责执行项目脚本。
- npm Registry:npm 默认使用的公共软件包仓库。
安装 Node.js 时通常会同时安装 npm,不需要单独下载安装 npm。
二、选择 Node.js 版本
打开 Node.js 官方下载页,日常开发和生产环境优先选择标记为 LTS 的版本。不要在教程中固定追随某个版本号,应根据项目的 engines、框架兼容性和维护周期选择。
- 只维护一个版本、初次学习:Windows 或 macOS 可直接使用官方安装器。
- 需要维护多个项目或切换版本:优先使用 Node.js 版本管理器。
- 生产服务器:固定经过测试的 LTS 版本,不要无验证自动跨大版本升级。
三、安装 Node.js
1. Windows
下载官方 64 位 MSI 安装器,按向导安装并保留“Add to PATH”。完成后关闭并重新打开 PowerShell。
2. macOS 与 Linux
更推荐使用版本管理器安装,以便不同项目使用不同 Node.js 版本。具体工具与命令应以其官方文档为准,不要把系统自带 Node.js 与版本管理器安装混用。
3. 验证安装
node --version npm --version # 查看可执行文件位置 where node # Windows where npm # Windows which node # macOS / Linux which npm # macOS / Linux
如果提示命令不存在,先重新打开终端,再检查安装目录是否已加入 PATH。
四、初始化 npm 项目
mkdir npm-demo cd npm-demo # 逐项填写项目信息 npm init # 全部使用默认值快速创建 npm init -y
初始化后会生成 package.json,它记录项目名称、版本、脚本、依赖和运行环境等信息。

一个简化的 package.json
{
"name": "npm-demo",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"start": "node src/index.js",
"test": "node --test"
},
"engines": {
"node": ">=22"
}
}
private: true 可以防止私有项目被误发布到 npm。engines 用于声明期望的 Node.js 版本范围,但是否强制执行还取决于使用环境和配置。
五、安装项目依赖
1. 生产依赖
应用运行时需要的包放在 dependencies:
npm install express # 简写 npm i express
2. 开发依赖
仅在开发、测试或构建阶段使用的工具放在 devDependencies:
npm install --save-dev eslint # 简写 npm i -D eslint
3. 安装指定版本
npm install express@5.1.0 npm install express@latest
4. 删除和更新依赖
npm uninstall express npm outdated npm update
不要把 node_modules 提交到 Git;应提交 package.json 和 package-lock.json,让其他环境可以恢复一致的依赖树。
六、本地安装、全局安装与 npx
1. 本地安装
默认安装到当前项目的 node_modules,项目代码通过 import 或 require 使用:
npm install lodash npm list --depth=0
2. 全局安装
全局安装主要用于需要在终端直接调用的命令行工具:
npm install --global <package-name> npm root --global npm list --global --depth=0
3. 使用 npx 临时执行
对于偶尔使用的命令,优先考虑 npx 或 npm exec,避免长期维护全局包:
npx <package-name> npm exec -- <command>
运行陌生包前应核对包名、来源和版本。npm 包可以包含安装脚本,拼写相近的恶意包可能带来安全风险。
七、package-lock.json 与可重复安装
package.json 通常保存允许的版本范围,package-lock.json 记录实际解析出的完整依赖树。团队项目应提交锁文件。
日常开发
npm install
该命令会根据 package.json 与锁文件安装依赖,必要时可能更新 package-lock.json。
CI/CD 与部署
npm ci
npm ci 要求已有 package-lock.json,若它与 package.json 不一致会直接失败;它不会改写这两个文件,适合自动化环境的干净安装。
八、理解语义化版本
常见版本格式为 主版本.次版本.修订版本,例如 3.5.2:
| 写法 | 一般含义 |
|---|---|
3.5.2 | 只接受精确版本 3.5.2 |
~3.5.2 | 允许兼容的修订版本更新,通常小于 3.6.0 |
^3.5.2 | 允许兼容的次版本和修订版本更新,通常小于 4.0.0 |
* 或 latest | 范围很宽,稳定项目中应谨慎使用 |
对 0.x 版本,插入号规则更严格,不能简单理解为允许所有 0.x 更新。最终安装版本以 package-lock.json 为准。
九、使用 npm scripts
在 package.json 的 scripts 中定义统一命令:
{
"scripts": {
"dev": "node --watch src/index.js",
"start": "node src/index.js",
"test": "node --test",
"lint": "eslint ."
}
}
执行脚本:
npm run dev npm start npm test npm run lint
脚本执行时,npm 会自动把项目的 node_modules/.bin 加入临时 PATH,所以通常不需要全局安装项目工具。
十、查看与切换 npm Registry
先查看当前源:
npm config get registry npm ping
npm 官方 Registry:
npm config set registry https://registry.npmjs.org/
网络环境确实需要时,可临时指定镜像:
npm install --registry=https://registry.npmmirror.com
也可以为当前项目设置,在项目根目录生成或更新 .npmrc:
npm config set registry https://registry.npmmirror.com --location=project
第三方镜像不是 npm 官方服务,可能存在同步延迟或供应链差异。发布包、处理私有包或排查版本问题时,应确认当前 Registry,并优先使用可信来源。
十一、代理与网络错误排查
先检查 npm 代理配置和系统代理环境变量:
npm config get proxy npm config get https-proxy npm config get registry npm ping
确认不再需要 npm 代理时,应删除配置,而不是把字符串 null 当作代理地址:
npm config delete proxy npm config delete https-proxy
遇到 ECONNREFUSED、ETIMEDOUT 或证书错误时,依次检查网络、DNS、代理、防火墙、系统时间和 Registry。不要用关闭 SSL 校验的方式掩盖证书问题。
十二、依赖与缓存维护
# 查看顶层依赖 npm list --depth=0 # 查看过期依赖 npm outdated # 检查已知安全问题 npm audit # 验证缓存完整性 npm cache verify
npm audit fix 可能升级依赖并改变行为,执行前应查看差异并运行测试;不要未经评估使用强制升级选项。
十三、常见问题
1. node 或 npm 命令找不到
重新打开终端,执行 where node 或 which node,确认安装路径和 PATH。多个安装来源并存时,应先清理冲突。
2. 全局安装权限错误
不要直接使用高权限命令反复安装。优先使用 Node.js 版本管理器,或改用 npx/npm exec 临时运行工具。
3. package.json 与锁文件冲突
在开发环境运行 npm install 重新解析并审查锁文件;CI 中使用 npm ci,让不一致尽早失败。
4. 安装后项目仍无法运行
检查 Node.js 版本、项目 README、环境变量和依赖安装日志。不要看到警告就一律忽略,尤其要关注不兼容版本、弃用包和安装脚本失败。
十四、推荐工作流
# 1. 验证环境 node --version npm --version # 2. 初始化项目 npm init -y # 3. 安装运行依赖和开发依赖 npm install express npm install --save-dev eslint # 4. 执行脚本和测试 npm run lint npm test # 5. 提交 package.json 与 package-lock.json # 在 CI 或部署环境执行 npm ci
更多信息可参考 Node.js 官方下载页、Node.js 与 npm 安装文档和 npm install 官方文档。