npm run 的工作原理和工作流程

1. 基本概念

npm run 用于执行在 package.json 文件的 scripts 字段中定义的脚本命令。

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "test": "jest",
    "build": "webpack --mode=production"
  }
}

2. 工作流程详解

2.1 命令解析阶段

npm run script-name

• npm 解析命令，提取脚本名称

• 查找当前项目的 package.json 文件

2.2 脚本查找过程

# npm 内部查找逻辑
1. 检查 package.json 中的 scripts 字段
2. 如果找到对应脚本，准备执行环境
3. 如果未找到，检查预定义脚本（start, test 等）
4. 如果都不存在，报错退出

2.3 环境准备阶段

# npm 会做以下准备工作：
- 创建子进程执行环境
- 设置 NODE_ENV 环境变量（如果未设置）
- 将 ./node_modules/.bin 添加到 PATH 环境变量开头
- 设置进程特定的环境变量

3. PATH 环境变量处理

这是 npm run 最重要的特性之一：

执行前 PATH 示例： /usr/local/bin:/usr/bin:/bin # 执行时 PATH 变为： ./node_modules/.bin:/usr/local/bin:/usr/bin:/bin

这意味着：

• 本地安装的依赖包中的可执行文件可以直接使用

• 不需要全局安装工具（如 webpack、jest 等）

4. 生命周期脚本

npm 支持自动执行的生命周期脚本：

{
  "scripts": {
    "prestart": "echo '准备启动...'",
    "start": "node server.js",
    "poststart": "echo '启动完成!'",
    
    "pretest": "echo '准备测试...'",
    "test": "jest",
    "posttest": "echo '测试完成!'"
  }
}

执行 npm run test 时的顺序：

prestart → start → poststart

5. 环境变量传递

5.1 内置环境变量

// 在脚本中可以访问的环境变量：
process.env.npm_package_name      // 包名
process.env.npm_package_version   // 版本号
process.env.npm_package_scripts_build // build脚本内容
process.env.NODE_ENV              // 环境变量

5.2 自定义环境变量

# 设置环境变量执行脚本
NODE_ENV=production npm run build

# 或者在 package.json 中
{
  "scripts": {
    "build:prod": "NODE_ENV=production webpack"
  }
}

6. 参数传递

6.1 向脚本传递参数

npm run script-name -- --arg1 value1 --arg2 value2

示例：

{
  "scripts": {
    "serve": "webpack serve"
  }
}

npm run serve -- --port 8080 --host 0.0.0.0
# 实际执行: webpack serve --port 8080 --host 0.0.0.0

6.2 在脚本中使用参数

{
  "scripts": {
    "deploy": "node deploy.js",
    "deploy:env": "node deploy.js --env $npm_config_env"
  }
}

npm run deploy:env --env=production

7. 实际工作流程示例

7.1 完整执行流程

# 用户输入
npm run dev

# npm 内部执行流程：
1. 读取 package.json
2. 找到 scripts.dev = "nodemon server.js"
3. 检查是否有 predev 脚本并执行
4. 将 ./node_modules/.bin 添加到 PATH
5. 创建子进程执行 "nodemon server.js"
6. 检查是否有 postdev 脚本并执行
7. 返回执行结果

7.2 复杂脚本示例

{
  "scripts": {
    "prebuild": "rimraf dist && mkdirp dist",
    "build": "webpack --mode=production",
    "postbuild": "node ./scripts/notify.js",
    "dev": "concurrently \"npm run server\" \"npm run client\"",
    "server": "nodemon server.js",
    "client": "webpack serve --hot"
  }
}

8. 高级特性

8.1 跨平台兼容性

{
  "scripts": {
    "clean": "rm -rf dist",           // Unix 系统
    "clean:win": "rmdir /s /q dist",  // Windows 系统
    "clean:cross": "rimraf dist"      // 跨平台解决方案
  }
}

8.2 条件执行

{
  "scripts": {
    "build": "webpack",
    "build:analyze": "npm run build -- --analyze",
    "deploy": "npm run build && npm run test && node deploy.js"
  }
}

8.3 使用工具函数

{
  "scripts": {
    "setup": "npm install && npm run build && npm run test",
    "reset": "npm run clean && npm install && npm run build",
    "ci": "npm ci && npm run test:coverage"
  }
}

9. 调试和排查

9.1 查看可用脚本

npm run
# 或
npm run --silent

9.2 调试脚本执行

# 查看实际执行的命令
npm run build --dry-run

# 显示详细日志
npm run build --loglevel verbose

9.3 错误处理

{
  "scripts": {
    "build": "webpack || echo '构建失败'",
    "test": "jest --passWithNoTests",
    "deploy": "npm run build && npm run test && node deploy.js"
  }
}

总结

npm run 的工作机制可以概括为：

1. 解析阶段：读取 package.json 中的 scripts 配置

2. 准备阶段：设置环境变量，修改 PATH

3. 执行阶段：按顺序执行生命周期脚本

4. 清理阶段：返回执行结果，恢复环境