企业官网建设流程全解析

说实话，这个问题我几乎每隔几天就会在群里看到一次。新手拿到一个 Node 项目，打开package.json，看到scripts这一坨，第一反应往往是：这些命令到底在干嘛？为什么有的叫dev，有的叫build，还有一堆看起来像是乱码的--xxx？更闹心的是，明明照着文档敲了npm run dev，却报一堆看不懂的错。

这篇就用大白话把scripts讲透。你会知道它是什么、怎么配、有哪些隐藏机制，以及实际用起来最容易踩的坑。不管你是刚接触前端、偶尔写点自动化脚本，还是想把自己的项目命令整理得舒服一点，看完应该都能直接上手用。

1. 先搞清楚：scripts字段到底是干嘛的

1.1 它的本质是一张“命令速查表”

先给一个最直白的定义：scripts是 npm 提供的一个配置项，用来把你在终端里要执行的一长串命令，存成一个简短的名字。就像你手机通讯录里存了 11 位电话号码，每次打电话不用输入全文，点一下“小李”就行。

默认长这样：

{ "name": "my-project", "scripts": { "dev": "vite", "build": "vue-tsc && vite build", "preview": "vite preview" } }

在这个基础上，你在终端敲npm run dev，npm 就会去读scripts里的dev字段，找到对应的值vite，然后交给系统的 shell 去执行。所以npm run后面跟的名字，并不是 npm 内建的指令，而是你自己在scripts里定义的钥匙。

那为什么要有这层“速查”呢？核心原因是：大型项目的启动命令往往不是一句能搞定的。

比如一个工程化前端项目，启动前可能要设环境变量、清缓存、生成类型定义、再开 dev server，如果这些全都靠脑子记住，每次部署都翻文档，基本等于自杀式开发。把它写进scripts，还能让同一个仓库的同事用同一套命令，避免“你那边怎么跑起来的”这种无效沟通。

1.2 为什么前端项目离不开它

现在你在 GitHub 上随便拉一个前端项目，scripts几乎是标配。它解决的不仅是“少打几个字”，更重要的是让命令行操作有了统一入口。

举个例子。一套典型的 Vue/React 项目，start 命令可能这么写：

{ "scripts": { "dev": "set NODE_ENV=development && vite --host 0.0.0.0", "build": "tsc --noEmit && vite build", "lint": "eslint . --ext .ts,.vue", "format": "prettier --write src/", "test": "vitest run" } }

如果没有 scripts，你拿到代码库之后，第一件事是去 README 里找“怎么启动”，找到一行命令，复制粘贴。有了 scripts，你只需要看 package.json 里的 keys，配合 README 里一句“npm install && npm run dev”，三分钟就能把项目跑起来。

另外，scripts也承担了“项目文档”的一部分职责。新同事入职，问“我们怎么打包”，你不用发一段教程，甩一句“看 package.json 的 scripts 里 build 就行”。团队越大，这个配置的作用越明显。

2. 命令写进scripts的语法和玩法

2.1 基础写法：键值对与容易踩的坑

scripts就是一个普通的 JSON 对象，key 是命令名，value 是真正执行的命令字符串。key 可以随便起，但要注意：不要使用 npm 已经占用的保留名，比如start、test都有默认行为，直接覆盖是没问题的，但你可能不小心触发预执行逻辑（后文会讲 pre/post），这会让新同事困惑。

value 部分写起来有几个细节。

第一，多个命令要按顺序执行，用&&连接。注意&&的特点是“前面成功才执行后面”。比如"build": "vue-tsc --noEmit && vite build"，vue-tsc 检查类型出错，vite build 就不会执行，避免带着类型错误强行打包。

第二，如果你想让两条命令前后没有依赖，可以并行执行。并行最简单的方式是&（在 Linux/macOS 的 bash 下），但 Windows 的 cmd 不太一样。跨平台最稳妥的方案是装一个concurrently，用法也很直白：

{ "scripts": { "dev:client": "vite", "dev:server": "node server.js", "dev": "concurrently \"npm:dev:client\" \"npm:dev:server\"" } }

npm:dev:client这种写法是 concurrently 支持的一种简写，会自动补齐成npm run dev:client。

第三，命令字符串里含有引号时，注意 JSON 转义。比如你想用cross-env设置环境变量，写成：

{ "scripts": { "serve": "cross-env NODE_ENV=production vue-cli-service serve" } }

注意，在 JSON 里，值如果包含双引号，必须写成\"。一旦转义漏写，整个 package.json 都会变成无效 JSON，npm install 都跑不了。

2.2 命令串联与并行：&&、&、concurrently

很多人刚上手时搞不清楚&&、&、;的区别，这里一次说透。

• &&：前一条命令退出码为 0 才继续执行后一条。如果前一条失败，整条链停住。
• ;：不管前一条成功失败，都会继续执行后一条。适合你希望“即使某一步挂了也要跑完”的场景，但实际 scripts 里用得少。
• &：在 Linux shell 里表示把当前命令放在后台，终端不会阻塞。但你在 npm scripts 里直接用&，经常会把日志混在一起，所以还是建议借助工具。

举例：一个打包任务，希望先删除旧产物、再生成新的，顺序执行即可：

{ "scripts": { "clean": "rimraf dist", "build": "npm run clean && vite build" } }

这里有个细节：clean写成独立脚本，再通过npm run clean在build里调用，比直接写rimraf dist && vite build更模块化。将来想在部署前单独清一次缓存，直接npm run clean就行，不用去改build。

如果希望两个 dev server 并行，用concurrently不是唯一方案，但确实是最省心的。它在 Windows PowerShell、cmd、Git Bash 下表现都比较稳定，日志前缀还能区分来源，这点比自己用&强很多。

2.3 给脚本传递参数：-- 和运行环境变量

这是很实用但很多人没搞明白的一块。

想在npm run build的时候临时加环境变量，比如指定 API 地址，有两个层次。

第一，npm scripts 会把值以字符串形式拼接。也就是说npm run task时，npm 会启动一个 shell 运行task对应的值，后面你可以用--往这个命令里追加参数。举例：

{ "scripts": { "lint": "eslint src" } }

执行：

npm run lint -- --fix

这里的--很重要。它的意思是“前面是给 npm 看的，把它们转给后面的脚本命令”。npm 在解析的时候，会把--后面的内容拼到 scripts 值的末尾，最终实际执行的就是：

eslint src --fix

如果不写--，--fix会被 npm 自己解析成参数，根本不会透传给你的脚本。这是新手最容易踩的坑，没有之一。

第二，往命令里注入环境变量。跨平台做法一般推荐cross-env：

{ "scripts": { "serve": "cross-env NODE_ENV=production node app.js" } }

为什么需要 cross-env？因为 Linux 和 macOS 是NODE_ENV=production node app.js，Windows 是set NODE_ENV=production && node app.js，语法完全不一样。为了不逼着 Windows 开发者改命令，就用 cross-env 统一处理。

在代码里通过process.env.NODE_ENV读取即可。注意，它和 Node 内置的 NODE_ENV 没有魔法绑定，只是按惯例使用。

3. 我最常用的一套scripts配置模板

3.1 前端项目常规脚本组合

给一个比较完整的前端工程模板，覆盖开发、构建、检查、测试、部署前检查：

{ "scripts": { "dev": "vite --host 0.0.0.0", "serve": "npm run dev", "build": "vue-tsc --noEmit && vite build", "typecheck": "vue-tsc --noEmit", "lint": "eslint src --ext .ts,.vue", "lint:fix": "eslint src --ext .ts,.vue --fix", "format": "prettier --write src/", "test": "vitest run", "test:watch": "vitest", "preview": "vite preview" } }

这套配置的思路很简单：每个命令只做一件事，复杂操作通过build这样的组合命令把多个步骤串起来。好处是调试时能精准控制。比如build失败，你分不清是类型检查失败还是 Vite 打包失败；但分拆成typecheck和vite build后，先单独跑npm run typecheck，几秒钟就能定位。

3.2 后端Node服务脚本与热重启

Node 后端项目，常见搭配是nodemon或者tsx watch。我的一个习惯是给不同环境配不同 start 命令：

{ "scripts": { "dev": "tsx watch src/index.ts", "start": "node dist/index.js", "build": "tsc -p tsconfig.json" } }

有的人喜欢把start命名成start:prod等，本质无所谓，关键是语义要清晰。团队协作时，约定越简单越好：npm run dev就是开发环境跑的，npm run start就是生产环境启动的。

再补充一个实际经验：如果你用 Docker 跑 Node 服务，scripts里最好不要写多余的交互性命令。tsx watch这种会前台阻塞、持续监听文件变化的进程，在容器里很容易把日志搞得很吵，一般生产构建时不需要 watch 模式。

3.3 与CI/CD配合的自动化命令设计

scripts 不只服务本地开发，也是 CI 流水线的操作核心。

我在 GitHub Actions / Jenkins 里通常这么安排：

{ "scripts": { "ci:lint": "eslint src --max-warnings=0", "ci:test": "vitest run --coverage", "ci:build": "npm run build" } }

为什么单独搞一套ci:*命令而不是直接复用本地的lint/test/build？因为本地开发可能有 watch 模式、交互式提示或特定参数。CI 环境则要求一次性执行、失败即退出、尽量严格。比如加了--max-warnings=0，只要有一个 warning，流水线就摆红，逼着大家把代码质量保持在较高水准。

在流水线配置文件里，调用方式是这样的：

- run: npm ci - run: npm run ci:lint - run: npm run ci:test - run: npm run ci:build

这里也引入一个常被忽略的点：npm ci和npm install不同，npm ci会严格按照 lockfile 安装依赖，适合 CI 环境，保证每次构建依赖版本一致。本地开发想升级依赖再用npm install。

4. 生命周期钩子：那些自动触发的隐藏脚本

4.1 pre/post钩子和便捷的test钩子

scripts 有一个对新手来说既惊喜又困惑的机制：当你执行npm run test的时候，npm 会自动检查是否存在pretest和posttest脚本，如果存在，会按顺序执行pretest->test->posttest。

这个机制对所有自定义命令都生效。也就是说，你声明了predoctor和postdoctor，执行npm run doctor时会先跑predoctor，再跑doctor，最后跑postdoctor。

一个常见用途是启动服务前检查依赖是否安装：

{ "scripts": { "predev": "node scripts/check-env.js", "dev": "vite" } }

每次npm run dev前，都会自动先跑一次环境检查。这里要注意：predev的生命周期是跟dev绑定在一起的，如果你在某处直接执行了 dev 对应值里的命令而非npm run dev，pre 钩子就不会触发。

test是 npm 内建命令，比较特殊。你可以直接npm test，效果等同于npm run test。它的 pre/post 钩子分别是pretest和posttest。比如你希望跑测试前先把上次生成的测试覆盖率报告清掉，就可以这么写：

{ "scripts": { "pretest": "rimraf coverage", "test": "vitest run" } }

这个机制的好处在于，不需要修改原有命令，就能给命令挂上“前处理”和“后处理”。但它也是一把双刃剑：如果你在项目里藏了一个postbuild，而负责执行npm run build的人完全不知道，那么构建完会多执行一些隐蔽操作，出了问题排查起来很痛苦。

4.2 钩子串起来以后实际会出现什么问题

我见过一个比较经典的坑：有的项目会把prepare钩子用来做依赖安装后的代码生成。prepare在npm install之后、npm publish之前都会执行。如果里面的脚本报错，整个安装流程就会卡住。

比如某次我调试一个项目，执行npm install一直报错，看日志才发现卡在了prepare: node scripts/generate-config.js。而这个脚本依赖.env文件，CI 环境里没这个文件，于是直接退出，导致依赖装不上。

类似这种钩子出现的问题，都有一个统一的排查思路：临时绕过钩子。npm 提供了--ignore-scripts参数，例如：

npm install --ignore-scripts

这样会跳过所有生命周期脚本，只装依赖。用来验证“问题是不是出在钩子上”特别快。

再补一个心得：不要把postinstall当成必需品，能不用就不用。如果团队里有多个成员在 Windows 和 macOS 混用，postinstall里的 shell 命令稍不注意就会在某个平台上爆掉。

5. scripts命令的常见问题与排查实录

5.1 command not found类错误

这是问得最多的一个问题。你配了：

{ "scripts": { "dev": "vite --port 3000" } }

然后执行npm run dev，结果报vite: command not found。

原因是：npm scripts 在执行时，会把node_modules/.bin这个目录临时加到 PATH 里。所以你根本没有全局安装 vite，也可以运行它——前提是 vite 以依赖形式装进了 node_modules。如果node_modules里没有，或者没有vite这个可执行文件，就会command not found。

排查步骤一般是：

• 确认package.json的devDependencies里有没有vite。
• 确认node_modules里vite文件夹存在，同时node_modules/.bin下有没有对应的可执行入口。
• 执行npm ls vite检查依赖树，看是否是版本冲突或安装不完整。
• 实在不行，删掉node_modules和 lockfile，重新npm install。

还有一种情况：依赖装好了，但当前 npm 执行环境不是项目里的 Node。比如你用 nvm 切换了 Node 版本，部分全局 CLI 可能连锁失效，也会导致奇奇怪怪的找不到命令。先node -v、npm -v确认环境。

5.2 Windows和macOS/Linux的命令差异

跨平台是 scripts 配置的一大痛点。核心矛盾是：npm scripts 的 value 传给的是系统默认 shell，Windows 上是 cmd.exe / PowerShell，Unix 上是 sh，两者语法不一样。

最常见的三个差异：

• 环境变量赋值：Linux 是NAME=value command，Windows 是set NAME=value && command。
• 删除目录：Linux 用rm -rf，Windows 用rimraf最省事。强烈建议用rimraf而不是依赖系统的rm或del。
• 路径分隔符：Linux 是/，Windows 是\。有时 reference 资源路径会出问题。

解决跨平台问题，有两条路线。路线一：给每个平台分别写命令，比如使用npm-run-all配合不同 subcommand，但维护成本高。路线二：引入跨平台工具，比如cross-env、rimraf、concurrently，把需要差异化的地方用工具抹平。我更推荐第二种，配置会清爽很多：

{ "scripts": { "build": "rimraf dist && cross-env NODE_ENV=production vite build" } }

5.3 脚本超时、退出码和日志问题

还有一个容易让人懵的地方：npm scripts 的退出码机制。任何一条命令执行完毕，Shell 都会返回一个退出码，0 表示成功，非 0 表示失败。npm 会把这个退出码透传出来，并决定这次npm run成功与否。

所以当你用&&组合命令时，只要其中一个环节退出码非 0，整条命令就是失败的。反过来，如果你在脚本里故意捕获了错误，但没有process.exit(1)，即使日志里已经打出“failed”，npm 也可能认为执行成功，CI 的检查就这样被漏掉了。

日志方面，npm 6 到 npm 7 之后输出格式有变化，脚本的 stdout / stderr 默认都会被打印。如果你的命令输出特别多，想减少噪音，可以在命令里加--silent（对 npm 自身的参数）或者用工具的重定向来收敛日志。注意，npm run dev -- --silent和npm run --silent dev含义完全不同，前者把--silent透传给 dev 里的命令，后者是隐藏 npm 自身的输出。

这里再给一个真实场景：我在做 CI 的时候发现npm run ci:test超时了，日志也没有明显报错。后来排查到是 Vitest 默认开启了 watch 模式，导致进程一直挂在那儿等文件变化。CI 环境里一定要给测试命令加run这种一次性执行参数，否则它会永远不退出。

还有一个经常被忽略的问题：scripts 命令里&&后面的程序没安装，错误信息可能非常具有迷惑性。例如vue-tsc && vite build，本地没装vue-tsc，前端第一段命令失败，你可能会误以为是自己 TS 配置写错了。如果看到这种组合命令失败，建议先把&&两侧分别单独跑一遍，定位哪一侧出问题再深入排查。

6. 几个值得刻进肌肉记忆的scripts小技巧

最后分享几个我不太可能写进正式文档、但实际帮了大忙的小操作。

第一，想查看当前项目都有哪些可用脚本，不用翻 package.json，直接敲：

npm run

不带任何脚本名，npm 会列出所有可用的 scripts，包括 pre/post 钩子，这个比手动翻文件快多了。

第二，如果想临时看某条命令最终被解析成什么，也可以借助npm run env来检查环境变量。不过更直接的做法是先用echo试跑：

{ "scripts": { "debug:env": "node -e \"console.log(process.env.NODE_ENV)\"" } }

先验证环境变量能被正确读到，再往真正的业务逻辑里接。别小看这一步，它能省掉很多“我以为环境变量生效了，其实根本没有”的折腾。

第三，使用npm pkg set直接往 package.json 里加脚本，不需要手动编辑 JSON。比如：

npm pkg set scripts.preview="vite preview"

这个命令会自动处理 JSON 转义和格式，避免手打引号出错。对经常在终端和编辑器之间来回切换的人特别友好。

第四，关于 scripts 里嵌套调用其他 scripts，npm run clean可以实现，但有更好的选择。如果你装了npm-run-all，可以用run-s clean build（串联）、run-p dev:client dev:server（并联）。它的日志格式比裸用&清晰得多，也更跨平台。

我在实际项目中，很少把某一条 scripts 写得特别长。最长也不会超过三个串联步骤。一旦超过，我会抽成独立的 Node 脚本文件，再在 scripts 里只写一句node scripts/deploy.js。这个做法的原因是：Shell 命令越长，转义和跨平台问题越多，把复杂逻辑放进 JS 文件里，能用编程方式做错误处理、日志、提示，可维护性强很多。

说回最本质的一点，package.json 里的scripts不是什么高深机制，它就是你在命令行世界里自定义的快捷键集合。快捷键好不好用，完全取决于你按什么思路组织它。用好了，一个项目的启动、检查、构建、部署就会变成几条极简的、团队里人人都能念出的口诀；用不好，它就是一团只有作者本人能看懂的咒语。希望这篇能把你在“命令怎么配、为什么这样配、报错怎么查”这条路上想省掉的弯路都省掉。