Node.js 与 npm 使用指南

什么是 Node.js？

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时，让你可以在浏览器之外运行 JavaScript。npm（Node Package Manager）是它的官方包管理器，也是全球最大的软件注册中心。

一句话总结：前端写 JS，后端也写 JS，npm 帮你装一切依赖。

安装 Node.js

推荐方式：nvm（版本管理器）

用 nvm 可以随时切换 Node 版本，不会污染系统环境：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 重新加载 shell
source ~/.bashrc

# 安装最新的 LTS 版本
nvm install --lts

# 查看当前版本
node -v
npm -v

常用 nvm 命令

nvm ls              # 列出已安装版本
nvm ls-remote       # 列出所有可用版本
nvm use 20          # 切换到 Node 20
nvm alias default 20  # 设为默认版本

其他安装方式

方式命令说明
系统包管理器sudo apt install nodejs npm版本通常较旧
官网安装nodejs.org 下载 .pkg/.msi简单直接但不好切换版本
Homebrewbrew install nodemacOS 用户常用

npm 基础操作

初始化项目

mkdir my-project && cd my-project
npm init          # 交互式创建 package.json
npm init -y       # 全部用默认值，快速创建

这会生成 package.json——项目的身份证，记录依赖、脚本、版本等信息。

安装依赖

npm install express              # 安装到 dependencies（生产依赖）
npm install -D typescript        # 安装到 devDependencies（开发依赖）
npm install -g nodemon           # 全局安装
npm install                      # 根据 package.json 安装所有依赖

卸载与更新

npm uninstall express            # 卸载
npm outdated                     # 检查过时的包
npm update                       # 更新所有包
npm update express               # 更新指定包

运行脚本

在 package.json 的 scripts 字段定义命令：

{
  "scripts": {
    "dev": "node src/index.js",
    "build": "tsc",
    "test": "jest",
    "start": "NODE_ENV=production node dist/index.js"
  }
}
npm run dev      # 运行自定义脚本
npm start        # start 和 test 可以省略 run
npm test

package.json 核心字段

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "我的应用",
  "main": "dist/index.js",
  "type": "module",
  "scripts": { ... },
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0"
  },
  "engines": {
    "node": ">=18"
  }
}

关键字段说明：

字段作用
main入口文件，别人 require('my-app') 时加载的文件
type"module" 启用 ES Module（import/export）
engines声明支持的 Node 版本
files发布到 npm 时包含哪些文件
binCLI 工具的入口命令

版本号规则（Semver）

格式：主版本.次版本.补丁版本（如 4.18.2）

{
  "express": "^4.18.0",   // ^ 允许次版本和补丁更新（>=4.18.0 <5.0.0）
  "react": "~18.2.0",     // ~ 只允许补丁更新（>=18.2.0 <18.3.0）
  "lodash": "4.17.21",    // 锁定精确版本
  "next": ">=14.0.0"      // 大于等于指定版本
}

记住：^ 是默认行为，大多数时候够用。~ 更保守，精确版本最安全。

package-lock.json

package-lock.json 锁定每个依赖的精确版本，保证团队所有人装到一模一样的包。

# 重要：永远把 lock 文件提交到 git
git add package-lock.json

# 如果依赖乱了，用这个清掉重装
rm -rf node_modules package-lock.json
npm install

npm 配置与镜像

查看和设置配置

npm config list              # 查看当前配置
npm config get registry      # 查看当前镜像源
npm config set registry https://registry.npmmirror.com  # 设为国内镜像
npm config delete registry   # 恢复默认

常用配置项

npm config set save-exact true        # 安装时锁定精确版本
npm config set fund false             # 关闭赞助提示
npm config set audit false            # 关闭安全审计提示

配置文件位置

文件路径优先级
项目级.npmrc（项目根目录）最高
用户级~/.npmrc中
全局级$PREFIX/etc/npmrc最低

npx：临时执行工具

npx 是 npm 5.2+ 自带的工具执行器，不需要全局安装就能跑命令：

npx create-react-app my-app       # 创建 React 项目
npx cowsay "你好世界"              # 临时跑一下 cowsay
npx eslint src/                   # 跑项目里的 eslint，不用全局装
npx http-server                   # 启动静态文件服务器

原理：先找本地 node_modules/.bin/，找不到就临时下载到缓存再执行。

常用场景速查

创建前端项目

npx create-vite my-app --template react-ts   # Vite + React + TS
npx create-next-app my-app                    # Next.js
npx create-expo-app my-app                    # React Native (Expo)

创建后端项目

npm init -y
npm install express
npm install -D typescript @types/node @types/express tsx

monorepo（多包项目）

// package.json
{
  "workspaces": ["packages/*"]
}
mkdir -p packages/{api,web,shared}
npm install                      # 自动链接本地包
npm install lodash -w api        # 只给 api 装 lodash

发布自己的包

npm login                        # 登录 npm 账号
npm publish                      # 发布（记得先改版本号）
npm publish --access public      # 发布 scoped 包为公开
npm unpublish my-package@1.0.0   # 撤销发布（24小时内）

常见问题

node_modules 太大？

# 查看最大的包
npx node-modules-size

# 用 .npmignore 或 package.json 的 files 字段控制发布内容
# 用 pnpm 替代 npm，天然节省磁盘空间

权限问题？

# 不要用 sudo npm install！改用：
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

网络慢/装不上？

# 切换镜像源
npm config set registry https://registry.npmmirror.com

# 或者用代理
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

npm vs yarn vs pnpm 速览

特性npmyarnpnpm
速度中等快最快
磁盘占用高中最低
lock 文件package-lock.jsonyarn.lockpnpm-lock.yaml
幽灵依赖有有无
monorepoworkspacesworkspacesworkspaces（原生支持最好）
推荐场景通用默认老项目新项目首选
如果是新项目，强烈推荐 pnpm——更快、更省空间、没有幽灵依赖问题。

速查卡

npm init -y                    初始化项目
npm install <pkg>              安装依赖
npm install -D <pkg>           安装开发依赖
npm install -g <pkg>           全局安装
npm uninstall <pkg>            卸载
npm run <script>               运行脚本
npm outdated                   检查过时包
npm update                     更新依赖
npm list                       查看依赖树
npm list -g --depth=0          查看全局安装的包
npm cache clean --force        清除缓存
npx <command>                  临时执行命令