NPM scripts脚本

前端项目日常开发中，你可能会反复敲这些命令：

vite                 # 启动开发服务器
vite build           # 打包构建
eslint . --fix       # 修复代码格式
vitest               # 运行测试

每次都要记住完整的命令，甚至带上参数——麻烦不说，还容易记错。

npm scripts 就是用来解决这个问题的，把常用命令起个短名字，存在 package.json 里，用 npm run 一键执行。

scripts 是什么

在 package.json 中有一个 scripts 字段：

{
  "name": "my-app",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "test": "vitest",
    "lint": "eslint . --fix"
  }
}

每个键值对就是一个脚本：

键：命令名（短、好记）
值：实际要执行的命令

执行方式：

npm run dev
npm run build
npm run test

敲 npm run dev 比敲 vite --port 3000 --host 简单多了，对吧？

为什么 scripts 这么重要

统一团队操作

团队里每个人开发环境可能不同（有人用 Windows，有人用 macOS），但 npm run dev 在任何系统上都一样。新人来了也不用问“怎么启动项目”，看 package.json 里的 scripts 就行。

简化复杂命令

比如你要同时启动前端和后端：

{
  "scripts": {
    "dev": "vite & node server.js"
  }
}

或者执行一系列任务：

{
  "scripts": {
    "build": "npm run lint && npm run test && vite build"
  }
}

一个命令搞定一串操作。

无需记忆具体工具命令

你用的是 Vite、Webpack 还是 Rollup？不重要。只要 npm run build 能打包就行——工具可以换，接口不变。

实用技巧

组合命令

用 && 串联（前一个成功才执行后一个）：

{
  "scripts": {
    "build": "npm run lint && npm run test && vite build"
  }
}

用 & 并行（同时执行）：

{
  "scripts": {
    "dev": "vite & node server.js"
  }
}

pre / post 钩子

NPM 支持在脚本前后自动执行钩子。比如你定义了 prebuild 和 postbuild，执行 npm run build 时会自动按顺序运行：

{
  "scripts": {
    "prebuild": "echo '开始构建...'",
    "build": "vite build",
    "postbuild": "echo '构建完成！'"
  }
}

执行 npm run build 的输出：

开始构建...
vite build ... (打包过程)
构建完成！

常见的钩子：

脚本	钩子
`build`	`prebuild` → `build` → `postbuild`
`test`	`pretest` → `test` → `posttest`
`install`	`preinstall` → `install` → `postinstall`

postinstall 特别有用——别人克隆项目后执行 npm install，会自动触发 postinstall，适合做初始化工作（比如生成类型声明）。

传递参数

如果脚本命令本身需要参数，用 -- 传递：

{
  "scripts": {
    "test": "vitest"
  }
}

npm run test -- --coverage    # 实际执行 vitest --coverage
npm run test -- --watch       # 实际执行 vitest --watch

如果不加 --，参数会被 NPM 拦截，传不到目标命令。

访问 package.json 中的变量

在脚本中可以用 npm_package_ 前缀访问配置：

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "info": "echo $npm_package_name $npm_package_version"
  }
}

执行 npm run info 会输出 my-app 1.0.0。

Windows 用户注意：用 %npm_package_name% 替代 $npm_package_name。

实际工作流

阶段	推荐脚本	说明
拉取代码后	`npm install`	自动触发 `postinstall`
日常开发	`npm run dev`	启动开发服务器
提交代码前	`npm run lint`	检查代码规范
提交代码前	`npm run test`	确保测试通过
打包部署	`npm run build`	生成生产产物
部署前验证	`npm run preview`	本地预览打包结果
遇到缓存问题	`npm run clean && npm run dev`	清理后重启

新手常见问题

Q：npm run dev 和直接敲 vite 有区别吗？

本质上没区别，npm run dev 只是通过 NPM 去执行 vite 命令。区别在于：

npm run dev 会使用当前项目 node_modules/.bin/ 中的可执行文件
直接敲 vite 需要全局安装或在 node_modules/.bin/ 的路径下

Q：node_modules/.bin/ 是什么？

本地安装的包如果有可执行文件（比如 vite、eslint），它们会被放在 node_modules/.bin/ 目录。npm run 会自动把这个目录加入 PATH，所以你不用写完整路径。

Q：Windows 和 Mac 的脚本写法不一样怎么办？

尽量用跨平台的命令。比如：

删除文件用 rimraf 而不是 rm -rf
设置环境变量用 cross-env

{
  "scripts": {
    "clean": "rimraf dist",
    "dev": "cross-env NODE_ENV=development vite"
  }
}

Q：脚本太长能换行写吗？

不能直接换行，但可以用反斜杠 \ 在 JSON 里续行（虽然不推荐，容易出错）。更建议拆分成多个脚本再组合。

本篇小结

npm scripts 是每个项目标配的自动化工具，记住这几点就够了：

scripts 写在 package.json，用 npm run 执行
pre/post 钩子自动触发，适合做前置/后置任务
node_modules/.bin/ 自动加入 PATH，本地安装的工具直接用
跨平台考虑用 rimraf、cross-env 等工具