1. 前提与推荐（先决条件）

1
2
node -v
npm -v

2. 建立项目（初始化 package.json）

在项目文件夹运行：

1
2
3
4
5
mkdir my-project
cd my-project
npm init        # 交互式初始化（一步步填写）
# 或更常用的：
npm init -y     # 快速生成 package.json（使用默认值）

生成的 package.json 示例：

1
2
3
4
5
6
7
8
9
10
11
{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

3. 安装依赖（最常用命令）

  • 本地依赖（项目内） — 安装并写入 package.json：
1
npm install express           # 默认把 express 加到 dependencies
  • 开发依赖（仅开发时需要，如测试/构建工具）：
1
npm install --save-dev mocha  # 或 -D
  • 全局安装（CLI 工具，注意：尽量用 npx，而不是全局）：
1
2
npm install -g typescript
# 推荐用 npx 执行一次性工具，例如： npx create-react-app my-app

参数总结：

  • --save（已废弃，npm 5+ 自动保存到 dependencies）
  • --save-dev / -D：保存到 devDependencies
  • -g：全局安装
  • --no-save：不写入 package.json

示例：创建一个简单的 express 项目

1
2
3
4
npm init -y
npm install express
# index.js
# const express = require('express'); const app = express(); app.get('/', (r,s)=>s.send('hi')); app.listen(3000);

4. package.json 的关键字段（用法说明）

  • dependencies：运行时所需包（生产环境）。

  • devDependencies：开发/测试/构建时需要的包。

  • scripts：npm 脚本（常用）

    1
    2
    3
    4
    5
    6
    "scripts": {
      "start": "node index.js",
      "dev": "nodemon index.js",
      "test": "mocha",
      "build": "webpack --config webpack.prod.js"
    }

    运行脚本：

    1
    2
    npm run dev   # 运行自定义脚本
    npm start     # 直接运行 start 脚本（不加 run）

  • main：模块入口文件。

  • version：语义化版本（semver），常用 npm version patch|minor|major 来自动修改（并可打 git tag）。

5. package-lock.json 与 node_modules

  • package-lock.json：锁定确切依赖树（保证可重复安装）；提交到版本控制。
  • node_modules：依赖实际安装目录，不提交到 VCS（加入 .gitignore）。
  • 在 CI 或生产环境推荐使用 npm ci（比 npm install 更快、更可预测）：
1
2
# CI 环境：清空 node_modules 并使用 lockfile 精确安装
npm ci

6. 升级 / 查看 / 卸载 依赖

  • 卸载：
1
npm uninstall lodash         # 删除并更新 package.json
  • 查看过时依赖：
1
npm outdated                 # 显示当前 / 想要 / 最新 版本
  • 升级（手动或使用 npm update）：
1
2
npm update lodash            # 尝试按 package.json 规则更新
npm install lodash@latest    # 指定安装最新版本

7. 安全审计（审计并自动修复）

  • 扫描已安装依赖是否有已知漏洞：
1
2
3
npm audit
npm audit fix                # 自动修复可自动修复的漏洞
npm audit fix --force        # 强制（可能升级破坏依赖）

8. npx（执行一次性包）

  • npx 可以临时执行包（不需全局安装）。
1
2
npx create-react-app my-app
npx cowsay "hello world"
  • 当你在 package.json 脚本里调用本地模块时，会优先使用 node_modules/.bin 的本地版本。

9. npm 脚本里使用环境变量（跨平台）

  • Linux/macOS：
1
2
3
"scripts": {
  "build": "NODE_ENV=production webpack"
}
  • Windows（兼容做法）：
    • 使用 cross-env：
1
2
3
4
5
npm install --save-dev cross-env
# package.json
"scripts": {
  "build": "cross-env NODE_ENV=production webpack"
}

10. 发布包到 npm 仓库（快速流程）

  1. 登录：
1
npm login           # 输入用户名、密码、邮箱
  1. 确保 package.json 中 name 唯一（或使用 scope：@yourname/pkg）和 version 合理。
  2. 发布：
1
2
3
npm publish         # 公共包默认发布到 registry.npmjs.org
# 如果是私有包或 scope 包，可能需要设置 --access public
npm publish --access public
  1. 更新版本并再次发布：
1
2
npm version patch   # 自动改 package.json 的版本并打 git tag
npm publish

注意：发布前检查 .npmignore 或 files 字段，控制哪些文件会被发布。

11. 私有仓库与 .npmrc

  • 使用私有 registry（例如公司私服）：
1
2
3
4
npm set registry https://registry.mycompany.com
# 或在项目根建立 .npmrc：
registry=https://registry.mycompany.com
//registry.mycompany.com/:_authToken=YOUR_TOKEN
  • .npmrc 可放在用户目录（~/.npmrc）或项目目录。

12. npm link（本地开发依赖联动）

  • 用于本地开发一个包并在另一个项目中测试：
1
2
3
4
5
6
7
# 在包项目里
cd my-local-lib
npm link          # 注册为全局符号链接

# 在使用该库的项目里
cd ../my-app
npm link my-local-lib   # 创建 node_modules/my-local-lib 指向全局链接
  • 结束时可用 npm unlink 清理。

13. Workspaces（monorepo，多包仓库）

  • npm 支持 workspace（v7+）：
    package.json（根）：
1
2
3
4
{
  "private": true,
  "workspaces": ["packages/*"]
}
  • 在 packages 下分别有子包，每个子包有自己的 package.json。运行 npm install 会在 monorepo 中统一安装并建立内部链接。
  • 适合管理多个相互依赖的包（monorepo）。

14. 常用进阶命令速查表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
npm init -y                      # 快速初始化
npm install / npm i              # 安装依赖
npm install pkg --save-dev -D    # 安装开发依赖
npm uninstall pkg                # 卸载
npm outdated                     # 查看过时包
npm update                       # 更新
npm audit / npm audit fix        # 安全审计
npm run <script>                 # 运行脚本
npm start                        # 运行 start 脚本
npm run build                    # 运行 build 脚本
npm ci                           # CI 使用：按 lockfile 安装
npm publish                      # 发布包
npm pack                          # 生成 tarball 包（测试发布）
npm view <pkg> versions          # 查看包版本信息
npm cache clean --force          # 清缓存（调试）

15. 常见问题与排错

  • 需要 sudo 安装全局包？
    • 不建议；改用 nvm 安装 Node，避免 sudo；或配置 npm 全局目录到用户目录。
  • node-gyp 编译失败？
    • 需安装 Python、C++ 编译工具链（Windows 上需要 Visual Studio 构建工具）。
  • 依赖冲突 / 锁文件失效？
    • 删除 node_modules + package-lock.json，然后 npm ci 或 npm install 重新安装。
  • 缓存问题？
    • npm cache verify 或 npm cache clean --force。
  • 包安装慢？
    • 改用国内镜像（淘宝镜像已不再官方维护，但可以在 .npmrc 指向其他镜像），或使用 pnpm/yarn 替代。

16. 最佳实践（小结）

  • 使用 package-lock.json 并提交到 git。
  • 开发依赖与运行时依赖区分清楚（devDependencies vs dependencies）。
  • 在 CI 中使用 npm ci 而非 npm install。
  • 避免不必要的全局安装，优先用 npx 或本地 script（./node_modules/.bin/...）。
  • 定期运行 npm audit 并及时修复漏洞。
  • 使用 nvm 管理 Node 版本，保证团队一致性（并提交 .nvmrc）。

17. 快速示例：创建并运行一个简单项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 新建
mkdir demo && cd demo
npm init -y

# 安装 express
npm install express

# 新建 index.js
cat > index.js <<'JS'
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('hello npm demo'));
app.listen(3000, () => console.log('listening 3000'));
JS

# package.json 脚本修改（也可手动编辑）
npm set-script start "node index.js"

# 运行
npm start
# 打开 http://localhost:3000