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 复用同一套入口。

json
{
  "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 通常可以直接写命令名,而不需要硬编码其磁盘路径。

npm scripts 从命令到子进程的执行流程

创建一个最小入口文件后即可验证脚本。文件 src/app.js 内容如下:

js
console.log('server booted');

通过 start 脚本执行时,预期结果为打印一行启动信息。

bash
npm run --silent start

预期输出:

text
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 中的实现。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 npm scripts

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通