技术 · 思考 · 实践 · 成长

首页/Vue3专栏/正文

Node.js 与 npm 环境搭建及常用命令完整指南

Vue3专栏549 次阅读

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,它记录项目名称、版本、脚本、依赖和运行环境等信息。

npm init 初始化项目示例

一个简化的 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 官方文档。

业精于勤而荒于嬉,行成于思而毁于随

评论交流

0 条评论 · 支持多级回复
验证码
暂无评论,来说说你的想法吧

相关文章

继续阅读