Node.js / 系统课时
配置 npm scripts
配置 npm scripts
项目里的启动、开发、测试和检查命令如果靠口头约定,很快会出现每个人执行方式不同的问题。把这些入口写进 package.json 的 scripts 后,开发者和 CI 都可以通过 npm run <name> 使用同一套命令,而不必记住底层参数。
学习目标
- 在
package.json中配置start、dev、test和check脚本 - 理解
npm run如何执行脚本,以及本地命令为什么不必写完整路径 - 为脚本传递额外参数,并避免把复杂业务逻辑全部塞进一行命令
给常用操作建立统一入口
下面以 Node 20+ 为例。start 用普通 Node 启动程序,dev 使用 Node 的 watch 模式,test 调用内置测试运行器,check 只检查入口文件语法。这些名字没有全部被 npm 强制规定,但保持职责清楚能让开发机和 CI 复用同一套入口。
{
"name": "scripts-demo",
"version": "1.0.0",
"scripts": {
"start": "node src/app.js",
"dev": "node --watch src/app.js",
"test": "node --test",
"check": "node --check src/app.js"
}
}配置生效后,npm run dev 会执行 node --watch src/app.js,npm run check 会执行语法检查。若团队使用较早的 Node.js 版本,应先通过 node -v 确认是否支持当前使用的命令参数,而不是把版本差异隐藏在脚本里。
从 npm run 到实际进程
执行 npm run start 时,npm 先读取当前项目 package.json 中对应的脚本,再交给系统 shell 执行命令。执行过程中,项目的 node_modules/.bin 会被加入脚本环境的 PATH,因此项目本地安装的 CLI 通常可以直接写命令名,而不需要硬编码其磁盘路径。

创建一个最小入口文件后即可验证脚本。文件 src/app.js 内容如下:
console.log('server booted');通过 start 脚本执行时,预期结果为打印一行启动信息。
npm run --silent start预期输出:
server booted--silent 只是在这个验证中隐藏 npm 自己打印的脚本标题,让输出更容易核对;项目是否使用该选项取决于日志需求。
给脚本传参数和组合生命周期
需要临时把参数传给底层命令时,在脚本名后使用 --。例如把 Node 的一个参数传给 src/app.js,命令形态是 npm run start -- --example;双横线后面的内容会传给脚本对应的命令,而不是由 npm 自己消费。
npm 还支持 pre<name> 和 post<name> 生命周期脚本。例如同时定义 pretest、test、posttest 后,执行 npm test 会按前置、主体、后置的顺序运行。它适合做轻量准备和清理,但不适合隐藏大量不可见步骤;如果一次测试前需要十几步构建和数据准备,更容易维护的做法是把流程写进独立的 Node 脚本,再让 npm script 只负责调用它。
避免依赖机器上的全局命令
项目脚本应优先调用项目本地依赖,而不是假设每个开发者都全局安装了某个 CLI。否则某台机器可能运行全局版本 8,CI 却安装项目要求的版本 9,最终出现本地通过、CI 失败的差异。
检查一个脚本是否适合交给团队时,可以确认三点:新克隆的项目只执行依赖安装就能运行;脚本中没有个人电脑的绝对路径;CI 调用的是 npm run test、npm run check 这类项目入口,而不是重新复制一套底层命令。这样调整工具版本时,只需要修改 package.json 中的实现。