企业官网建设流程全解析

说实话，很多写了好几年 JavaScript 的同学，对package.json里的scripts也就停留在“会跑 npm run dev 和 npm run build”的水平。真要被问到“scripts 这个配置的命令到底是什么意思”——一时半会儿还真不一定能说得利索。这不算冷知识，反而越是基础的东西越容易含糊，因为平时天天在用，反而没想过它背后的机制是怎么转起来的。

我当年带前端组的时候，经常遇到一种情况：项目明明用的是同一个脚手架，可组员电脑上跑出来的效果就是不一样。后来追根溯源，大半问题都出在 scripts 里写的命令上，要么是直接拷贝来的脚本没考虑跨平台，要么是环境变量在 Windows 上根本不生效。从那时候起，我就养成了一习惯：拿到一个新项目，第一件事就是翻 package.json 的 scripts 字段，看它命令怎么写的、钩子怎么挂的，基本就能猜出这个项目的自动化程度和作者的工程素养。

这篇文章不打算只做名词解释，我尽量把 scripts 的底层机制、常用写法、组合套路和实际踩坑都摊开来讲。不管你是刚入门的前端新人，还是写了很多年脚手架的资深选手，应该都能在里面找到点能直接拿来用的东西。

1. scripts 命令的本质与设计思路

1.1 scripts 到底是什么

先把这个最基础的问题讲明白。package.json是 Node.js 项目的元数据文件，里面记录了项目的名称、版本、依赖、入口文件等信息。而scripts字段，是其中专门给包管理器（npm、yarn、pnpm 都支持）用的“命令速查手册”。它长这样：

{ "scripts": { "dev": "vite", "build": "tsc && vite build", "start": "node server.js", "test": "jest" } }

scripts的值是一个对象，对象的每个键是命令的“别名”，每个值是一段真正的 shell 命令字符串。运行npm run dev时，npm 会在你当前项目的根目录下，把vite这段字符串交给系统的 shell 去执行。换句话说，所谓 npm scripts，本质上就是一个“命令映射表”：你给我一个短名字，我还你一次真实的命令行执行。

很多人忽略了一个事实：scripts 里的命令并不是 Node.js 语法，而是 shell 语法。这意味着它天然依赖操作系统。同样是rm -rf dist，在 Linux/macOS 上没问题，在 Windows 的 cmd 里可能就是一句不认识的话。这一点后面会专门讲。

还有一个大家容易混淆的点：不是说只有 npm 才有 scripts，pnpm、yarn 都支持。只要你安装了 Node.js，npm 就会自带，所以这是 Node 生态里最通用的任务执行方式。就算你不用 Vite、不用 React，只要你的项目里有 package.json，你就可以用它来编排任何命令行操作，比如压缩图片、同步文件、启动数据库、跑定时任务，统统可以。

1.2 为什么需要 scripts 而不是直接执行命令

既然 scripts 里的值最终都是 shell 命令，那为什么不直接在终端里敲命令？这就要说到统一入口的价值了。

先讲团队协作。一个项目通常有多个成员参与，每个成员的本地环境千差万别。有的人用 Windows，有的人用 macOS，有的人习惯用 npx，有的人全局装了某些工具。如果在 README 里写“请执行vite启动开发服务器”，新同学很可能卡在“vite 命令不存在”这一步，因为他的项目根本没有全局安装 vite。而有了 scripts，只需要写npm run dev，npm 会自动把node_modules/.bin加进 PATH，本地安装的 vite 就能被找到。这样一来，无论成员是什么系统、有没有全局工具，操作入口就统一了。

其次是心智负担。复杂项目的启动命令往往很长，比如要同时起前端、起后端、监听文件变化、生成类型定义。把这些细节全部收进 scripts 后，团队成员只需要记住一个简短的名字。这跟遥控器上的“一键观影”按钮是同一个道理，把背后的信号源切换、音响设置、灯光调节全封装起来。

还有一个特别重要的设计——生命周期钩子。npm scripts 在执行某个脚本之前和之后，会自动检查有没有对应的pre和post前缀脚本。举个例子，你配置了prebuild和build，执行npm run build时，npm 会先跑prebuild，再跑build，如果存在postbuild，最后还会跑它。这种机制天然适合做构建前的清理、构建后的部署通知，不需要额外引入工具。光是这一个设计，就比很多自制任务脚本优雅得多。

2. 核心细节解析：scripts 的语法与执行机制

2.1 JSON 结构与键值约定

scripts 虽然用起来简单，但它有非常严格的语法约束。我在代码评审时看到过不少人在这里踩坑，所以把几个关键约定单独拿出来说。

第一，scripts字段的值必须是对象，键值对中的值必须是字符串。有些开发者在别处习惯了写数组，也想当然地在 scripts 里写数组，比如：

{ "scripts": { "lint": ["eslint .", "prettier --check ."] } }

但这是不合法的。npm 不会按数组顺序执行，它期望的只是一个字符串。如果你确实想同时执行多条命令，用&&连接即可，这是 shell 本身就支持的语法。

第二，键名虽然可以随意起，但 npm 内置了几个特殊脚本名，它们拥有默认行为。start和test尤其特殊：npm start和npm test不需要加run，直接就能运行。restart的默认行为是依次执行stop、restart、start，如果你自定义了restart，则优先按你的来。stop也一样，可以直接用npm stop触发。

第三，JSON 本身不支持注释，但 scripts 值里的命令却经常需要注释。这个矛盾让不少人头疼。我的变通方案是：把复杂的命令拆成多个短脚本，名字本身就是注释；或者单独维护一个scripts.md文档；再或者用//作为键名（因为 npm 并不限制键名形式），但这种方式不太推荐，因为有时会触发 shell 的路径解析问题。归根结底，简洁清晰的脚本名是最可靠的“注释”。

还有一个细节：npm run后面带上任意一个不存在的脚本名，npm 会输出一个包含所有可用脚本的列表来提醒你。这个输出列表其实是排查问题的好入口，后面我会专门讲。

2.2 生命周期钩子：pre、post 与特殊命令

先看一个最典型的例子：

{ "scripts": { "prebuild": "rimraf dist", "build": "tsc && vite build", "postbuild": "node ./scripts/notify.js" } }

执行npm run build时，实际的执行顺序是：prebuild->build->postbuild。这里的pre和post不是命令本身，而是 npm 对脚本名的约定前缀。

这套机制的价值在于，它可以让你把任务分阶段组织，而不需要额外引入任务管理工具。比如：

• 构建前清空旧产物（prebuild）
• 构建后自动拷贝静态资源或发个通知（postbuild）
• 安装依赖前做权限校验（preinstall）
• 安装依赖后自动初始化配置文件（postinstall）

特别要注意的是pre钩子的失败会阻断主命令的执行。如果你在predev里写了一个退出码非零的命令，哪怕只是拼写错误，npm run dev也会直接失败。这个特性如果利用得好，可以当作“前置校验”；利用不好，就是莫名其妙的卡点。

除了用户自定义脚本，npm 自身也有一系列生命周期事件，比如install、uninstall、publish、version等。这些事件对应的钩子脚本会在特定时刻自动触发，比如prepare会在安装依赖时执行，常用来做构建工作；prepublishOnly会在发布前执行，常用来做测试和构建的最终校验。新手最容易混淆的是prepublish和prepublishOnly，简单说，prepublish在本地npm install时也可能触发，而prepublishOnly只会在发布流程中触发。实际开发中我更推荐用prepare来做构建，用prepublishOnly做发布前检查，这样语义更清晰，也不容易误触发。

2.3 npm run 的 PATH 魔法与 shell 细节

这一点是 scripts 的“隐藏超能力”，也是很多人没完全吃透的地方。

正常情况下，你在终端里输入vite，系统会在 PATH 环境变量里寻找名叫 vite 的可执行文件。如果你没有全局安装 vite，大概率会报 “vite: command not found”。但如果你在项目里执行npm run dev，即使脚本写的是vite，npm 也能把它跑起来。

秘密在于 npm 在运行 scripts 之前，会临时修改 PATH，把当前项目根目录下的node_modules/.bin目录加到 PATH 的最前面。这个目录里是什么？是项目依赖里那些带有bin字段的包生成的可执行文件。比如你安装了 vite，node_modules/.bin 里就会多出一个 vite 的超链接，npm 推高了它的优先级，于是脚本里的vite就能被正确解析。

这个机制带来几个直接结论：

1. 项目本地安装的 CLI 工具，可以在 scripts 里直接使用命令名，不需要 npx，也不需要写完整路径。
2. 这个 PATH 修改只对npm run启动的子进程生效，不会污染你当前的终端会话。所以你在终端里手动敲vite，可能照样找不到命令。
3. 如果你在 scripts 里调用另一个 npm 脚本，比如"build": "npm run lint && vite build"，内层的 npm 也会继承这个 PATH，所以工具链可以层层嵌套，不会丢上下文。

再补充一个传参细节：如果你想给脚本命令追加参数，需要用到--分隔符。比如你定义了"build": "vite build"，想传递一个自定义模式参数--mode staging，直接跑npm run build -- --mode staging即可。npm 会把--mode staging原样附加到命令末尾，最终执行的就是vite build --mode staging。如果不写--，npm 很多时候会吞掉参数，甚至报错。这个坑我见过太多次了，尤其是新人第一次尝试给 scripts 传参时，十有八九会困惑“为什么我的参数没传进去”。

3. 实操过程：从零编写一套可用的 scripts

3.1 一份典型的前后端项目配置

纸上谈兵没意思，直接上一份我实际用过的项目配置，逐条拆开讲设计思路。

{ "scripts": { "dev": "vite --open", "build": "tsc -p tsconfig.build.json && vite build", "preview": "vite preview", "start": "node server.js", "test": "vitest run", "test:watch": "vitest", "lint": "eslint . --ext .ts,.vue --fix", "format": "prettier --write \"src/**/*.{ts,vue,json,md}\"", "clean": "rimraf dist coverage", "build:analyze": "npm run build && vite-bundle-visualizer" } }

• dev是日常开发用的，--open让 Vite 自动打开浏览器。选择是否加--open要看团队习惯，有的人喜欢自己开，有的人嫌启动时弹窗烦，这个可以按需调整。
• build里我特意加了tsc -p tsconfig.build.json，先做类型检查再打包。很多项目把类型检查放在单独脚本里，构建时不检查，结果部署上去才发现类型错误，那就晚了。我倾向于在构建链路里先过一遍类型，宁可多花几秒钟，也不让坏代码进入产物。
• clean用了rimraf而不是rm -rf，原因就是跨平台。rimraf是 Node 生态里最常用的跨平台删除工具，Windows 下也能稳定运行。
• test:watch和test分开，是因为日常开发时我们希望测试能在文件变化时自动重跑，而 CI 里只需要跑一次。同一个底层命令，通过不同脚本名区分场景，这是 scripts 设计的常见套路。
• build:analyze这种脚本名里有冒号，是业界约定俗成的“命名空间”写法，用来把相关联的脚本归组。npm 本身不强制，但对维护者很友好，一看就知道是 build 类的变体。

新手最容易犯的错，是把所有命令塞进一个超长字符串里。比如"build": "rimraf dist && tsc -p tsconfig.build.json && vite build && npm run lint"。这看起来是“一步到位”，实际调试起来非常痛苦，因为你不知道到底是哪一步挂的。正确做法是拆分成独立的小脚本，让每个脚本只干一件事，然后在需要时用&&串联。这不仅利于排查，也利于在 CI 里灵活组合。

3.2 脚本的串联、并联与复用

scripts 的命令本质上就是 shell 命令，所以 shell 的操作符都可以用来编排流程。

&&是“前一个成功才继续执行后一个”，这是最常用的串联方式。;是“不管前面成不成功，都继续执行后一个”，但它的可用性取决于 shell，在 Windows 的 cmd 里支持度并不好。所以我一般只推荐&&和||。

并联则麻烦一些。单纯在 scripts 里写A & B，含义是“后台运行 A，紧接着在前台运行 B”，如果 A 是一个长驻进程，&会把控制权交还给 shell，这时脚本可能很快就跑完了，不会真正等待 A 结束。这不是我们通常理解的“并行执行”。如果想真正并行跑两个长驻服务，更靠谱的方案是用concurrently：

concurrently "npm:dev:server" "npm:dev:client"

concurrently是一个专门做命令并发的 Node 工具，它会把多个进程同时拉起来，并统一管理输出流和退出码。我用它最多的时候，是同时启动一个后端 NestJS 服务和前端 Vite 开发服务器。注意，脚本里的命令前缀可以用npm:语法，它表示“跑同名的 npm scripts”，比手写npm run dev:server要简短。

脚本复用也是一个容易被忽略的点。比如你有一个构建脚本，既想被本地的build调用，又想在发布前置钩子里单独执行，那么你可以把它抽出来作为中间脚本：

{ "scripts": { "build:compile": "tsc -p tsconfig.build.json && vite build", "build": "npm run clean && npm run build:compile", "prepublishOnly": "npm run lint && npm run test && npm run build:compile" } }

这种“小命令组合成大命令”的思路，和函数组合非常像。复用脚本要注意一点：被复用的脚本通常会作为子进程运行，子进程退出码会传递到父进程，所以如果被复用脚本失败，外层脚本也会被判定为失败，这个行为是符合直觉的。

3.3 参数传递与动态控制

前面提过，npm run build -- --mode staging这种传参方式可以把--mode staging原样追加到命令后面。但要注意，npm 只追加，不解析。如果你的脚本里原本就有参数，比如"dev": "vite --host 0.0.0.0"，运行npm run dev -- --port 3000时，最终命令是vite --host 0.0.0.0 --port 3000，追加的参数在最后，这在大多数 CLI 工具里都能被正确解析，但也有一些工具对参数顺序敏感，需要特别留意。

除了传参，npm 还会向 scripts 注入一系列以npm_开头的环境变量。比如：

• npm_lifecycle_event：当前运行的脚本名。
• npm_package_name：包名。
• npm_package_version：版本号。
• npm_config_registry：当前 registry。

这些变量在脚本执行时对子进程可见。如果你的脚本里需要知道“我当前是在哪个阶段运行的”，可以在命令里使用它们。比如"postversion": "npm run build && git push --follow-tags"，构建包里可以读取process.env.npm_package_version来生成带版本号的产物。

还有一个常见的场景是环境变量本身。比如在 Linux/macOS 下，你可以写"build": "NODE_ENV=production webpack"，但在 Windows 的 cmd 里，NODE_ENV=production这种赋值语法是不被支持的，会直接报“不是内部或外部命令”。这个问题我在 Windows 环境和 CI 环境同时并行时几乎必踩。解决方案就是引入cross-env：

cross-env NODE_ENV=production webpack

cross-env会先解析这些赋值语法，转换成当前平台支持的写法，然后再执行后续命令。如果你的团队里有人用 Windows，这里的教训就四个字：老老实实用 cross-env。

4. 常见问题与排查技巧实录

4.1 Windows 与 Linux/macOS 的环境差异怎么处理

这是 scripts 跨平台问题的高发区，也叫“环境差异”问题。我把它单独拿出来，是因为实在太多人遇到。

第一个差异是命令本身。rm -rf是 Unix 系命令，Windows 下没有。解决方案是使用 Node 生态的跨平台替代品，比如rimraf删除文件，mkdirp创建目录。或者干脆写一个小 Node 脚本，用fs.rmSync之类的 API 来实现，再把脚本路径接到 scripts 中。

第二个差异是命令前缀。NODE_ENV=production在 PowerShell 和 cmd 里写法不同，PowerShell 也许支持$env:NODE_ENV="production"，但 cmd 不支持。这个必须用cross-env统一。

第三个差异是路径分隔符。Windows 用\，Unix 用/，在 scripts 里写硬编码路径非常容易翻车。尽量使用相对路径，避免在命令里拼绝对路径。如果必须拼，可以用 Node 的path.join生成，再把它输出给脚本使用。

第四个差异是 shell 本身。npm 在 Unix 系统上用sh，在 Windows 上优先用cmd.exe，如果你装了 Git Bash，可以通过 npm 配置项script-shell指定用它。这个配置不建议全局改，因为它会影响你所有项目，最好在项目根目录放一个.npmrc，里面写script-shell = "C:\\Program Files\\Git\\bin\\bash.exe"。但这也会引入新的兼容问题，比如 bash 模式下路径转义规则又变了。所以我的经验是：尽量让脚本用纯 Node 工具，少依赖 shell 特性。

4.2 脚本运行失败的常见原因

我把这几年遇到的高频问题整理成了一张排查顺序表，照着走基本能定位问题。

先看 package.json 里的脚本字符串本身。最常见的拼写问题是命令名与依赖名不一致。比如你安装了eslint，但脚本里写的是eslint . --fix，这没问题；可你安装了typescript却没安装tsc对应的 bin，脚本里写tsc就找不到。工具类的 bin 名称不一定等于包名，安装完之后去node_modules/.bin里 ls 一下，确认实际的可执行文件叫什么，比靠记忆靠谱得多。

再检查环境变量。如果脚本里用了env或者process.env读取的变量，而你没有在启动前注入，脚本可能跑到一半报 undefined。在本地调试时，我会用printenv或node -p "process.env"把子进程环境打印出来，对照 npm 注入的变量。

然后是 Node 版本问题。有些工具要求 Node 18+，某些旧项目用 Node 14，npm 启动时如果版本不匹配，早期症状往往是“命令找不到”或者“某个依赖加载失败”。建议在 scripts 里放一个"predev": "node -v"之类的前置调试脚本，先把环境版本打出来，再来看后续报错。

最后是退出码问题。脚本不报错但不干活，很多时候是 CLI 工具认为“没有需要处理的内容”，比如prettier --check .在一个没有文件匹配的目录里，可能直接返回 0，给人一种“成功”的错觉。遇到这种问题，不要只看退出码，要把实际输出打出来，确认它执行了预期操作。

4.3 调试 scripts 的小工具与技巧

先推荐一个基础技巧：直接运行npm run（不带脚本名），npm 会输出当前项目的全部脚本列表。这个列表看似简单，其实信息量很大——它会告知你每个脚本的完整命令，方便你在不打开 package.json 的情况下快速核对。

接着是npm run env这个命令，它会列出 npm 运行脚本时注入的全部环境变量。排查“脚本里是不是少了某个环境变量”时非常有用。很多人不知道这个内置命令，实际上它的价值比想象中高。

还有一个常见的坑：脚本输出中文乱码。Windows 终端默认代码页（比如 GBK）和脚本里输出的 UTF-8 中文不一致，导致看到一堆乱码。解决办法一般是把终端切换到 UTF-8：在 cmd 里执行chcp 65001，或者用 VS Code 的终端并设置编码为 UTF-8。

最后推荐一个习惯：写脚本时不要图省事，日志要保留。比如在 scripts 里加一句"postbuild": "echo Build finished at $(date)"，利用 shell 命令记录时间戳，方便定位构建耗时波动。

最后再分享两个小技巧

第一个是关于脚本命名。我见过不少项目把脚本名取得很随意，比如"a": "vite"、"b": "node build.js"——这种命名虽然能用，但可读性极差。我的习惯是：动词开头，名词结尾，比如build:prod、dev:client、test:unit。冒号前是动作，冒号后是场景，一眼就能看明白。

第二个是关于 script 的依赖关系。写 scripts 前先把工作流画在纸上，想清楚“哪个阶段需要哪个工具，哪些操作必须串行，哪些可以并行”。如果你发现一个脚本里塞了四五种工具的调用，那大概率是设计上出了问题。合理的拆分会让你后续维护和排障都轻松很多。

这套东西用熟了以后，你会慢慢形成一种感觉：package.json 的 scripts 字段就是项目的操作说明书，写得越清晰，团队协作越顺畅。希望这篇文章能帮你把这张说明书写得更好。