企业官网建设流程全解析

第一次拿到一份package.json，很多人最先注意到的往往是dependencies里那一长串依赖名，反而忽略了上方那个看起来平平无奇的scripts配置字段。说实话，我刚接触Node生态那会儿也一样，总觉得scripts不过是个放快捷命令的地方，甚至一度懒得往里写，直接在终端敲长命令。后来在真实项目里吃了不少亏——有人部署前忘了跑构建、有人本地测试命令不一致、有人Windows上环境变量直接崩——才意识到package.json里的scripts，其实是整个项目工程化的第一块基石。

它说白了就是一张挂在package.json里的命令别名表：key是脚本名，value是真正要执行的shell命令。你不需要把一长串参数背得滚瓜烂熟，只要注册一次，然后记住npm run dev、npm run build这种短命令就够了。这篇文章我会结合自己前后端项目里的实际经验，拆解scripts的价值、写法、原理，以及那些文档里不会写、但你在跑脚本时大概率会踩到的坑。无论你是刚入门的小白，还是已经写了两年项目但没认真研究过scripts的老手，应该都能从中捞到一点东西。

1. scripts到底解决什么问题

1.1 本质：一张挂在package.json上的命令别名表

package.json里和scripts相邻的字段，像version、main、type，负责定义包的身份和入口，而scripts单独负责一件事：定义“这个项目可以执行哪些命令”。每一对key和value，key是你可以记住的短名字，value就是丢给shell执行的一整条命令。

举个例子：

{ "scripts": { "dev": "vite --port 5173", "build": "vite build" } }

在终端敲npm run dev，实际被执行的命令就是vite --port 5173，效果跟你自己敲完整命令完全一样。区别在于：你不需要每次去记端口号，也不需要在团队里反复解释“启动项目要敲哪条命令”。

有人可能觉得，这不就是套了一层壳吗？确实，它的本质就是壳，但这层壳的价值远比表面看起来大。我见过不少项目，启动命令从node server.js一路进化成webpack serve --config config/webpack.dev.js --progress --color，如果不放进scripts里，三分钟后你自己都记不住，更别说新来的同事。把它注册成dev，就变成了一件确定性的事。

1.2 团队统一入口的价值

scripts更大的价值体现在团队协作上。一个仓库往往同时有前端、后端、定时任务、脚本工具，如果每个人都按自己的习惯敲命令，轻则命令不一致，重则有人用了不同版本的工具链，出现“明明代码一样，你机器能跑我不能跑”的诡异情况。

把命令统一收进scripts之后，项目的操作入口就被固定下来了。新同事入职看package.json里的scripts，基本就能知道这个项目能干什么、日常怎么跑。我自己的习惯是：把常用的dev、build、test、lint全部写成短名，然后在README里的开发指南部分只写“npm run dev”，不写具体启动命令。这样即使哪天我把底层工具从webpack换成了vite，团队也不需要重新学习，只要scripts里的名字不变，大家照旧跑npm run dev就行。这就是脚本层带来的稳定性。

顺带说一句，npm对start、test这类名字有内置快捷方式，你直接敲npm start、npm test，效果等同于npm run start、npm run test。所以你会看到新项目初始化后，默认的test是一条“报错脚本”——echo \"Error: no test specified\" && exit 1，那是npm在提醒你，这个字段应该被改造成真正有用的命令。

1.3 藏在名称里的生命周期钩子

npm的scripts里藏着一个不太起眼但很好用的机制——生命周期钩子。对于任意一个名为xxx的脚本，npm会自动为它寻找prexxx和postxxx两个兄弟脚本，并在执行xxx之前和之后自动运行它们。

打个比方，你配置了：

{ "scripts": { "prebuild": "npm run lint", "build": "vite build", "postbuild": "node scripts/notify.js" } }

那么敲一次npm run build，实际执行顺序是：先跑prebuild里的lint，再跑build本身，最后跑postbuild里的通知脚本。你不用另外写复杂的串联逻辑，只要按命名规则取名，npm就帮你按这个顺序编排好了。

我实际项目里最常用的钩子是predeploy和postdeploy。比如deploy负责执行发布命令，predeploy自动先跑一遍构建，postdeploy打一个版本tag或者调用接口做健康检查。这里要提醒一点：钩子是串行的，前一个失败了后面不会继续，这既是保障也是约束。如果你的postbuild里放了很重的任务，构建时间会被明显拖长，所以钩子适合放轻量操作，重任务尽量拆成独立的脚本手动触发。

注意：npm还保留了一批特殊命名的生命周期脚本，比如preinstall、postinstall、prepublishOnly。它们不是跟着某个自定义脚本走的，而是在npm install、npm publish这些动作触发的固定时机执行。husky能帮你自动配置git hooks，靠的就是postinstall这个时机。

2. 高频场景下的scripts实战配置

2.1 开发启动与构建发布

先看一组最核心的配置，几乎任何前端工程都会用到：

{ "scripts": { "dev": "vite --host 0.0.0.0 --port 5173", "build": "vite build", "preview": "vite preview --host 0.0.0.0 --port 4173" } }

dev负责本地开发，--host 0.0.0.0是为了让局域网里其他设备也能访问，在联调时特别有用。build负责生产构建，preview则用来预览构建产物。这三个名字在Vue和React生态里已经成了默认约定，大家看到就知道什么意思。

我踩过的一个坑是：build之前不清空dist目录。老版本的vite和webpack有的会自动清，有的不会，结果就是dist里残留旧文件名，部署到服务器后出现“明明构建成功，页面上还是旧版本”的诡异问题。后来我在build脚本里统一加上清理步骤，比如用rimraf先删再构建：

{ "scripts": { "build": "rimraf dist && vite build" } }

这里用了rimraf而不是rm -rf，是因为在Windows的原生cmd里根本没有rm -rf这种写法，rimraf是跨平台工具，macOS、Linux、Windows通吃。这个问题在后面的跨平台部分我还会细说。

2.2 测试、代码检查与格式化

测试和代码检查这一组，也是scripts的重头戏。最常见的组合是：

{ "scripts": { "test": "vitest run", "test:watch": "vitest", "lint": "eslint . --max-warnings=0", "lint:fix": "eslint . --fix", "format": "prettier --write \"src/**/*.{ts,tsx,vue}\"" } }

因为prettier和eslint这类工具会把配置文件和命令参数拖得很长，非常适合放进scripts。而test和test:watch这样的拆分很有讲究：test用于CI场景，一次性运行；test:watch用于本地开发，文件变化后自动重跑，非常省心。

关于参数传递，这里要单独说。很多人想在npm run后面直接追加参数，比如npm run test --watch，结果发现参数被npm自己吃掉了，根本传不到vitest。正确写法是加一个--分隔符：

npm run test -- --watch npm run lint -- --fix

命令实际执行时，npm会把--之后的内容原样拼接到scripts的value末尾，相当于vitest run --watch、eslint . --fix。这个细节我见过太多人踩坑了，记住：npm run本身只负责启动脚本，它身后的所有额外参数，都必须先隔一个--。

2.3 数据初始化与mock服务

实际业务项目里，光有dev和build是远远不够的，数据库相关的脚本也很常见。我参与过的项目，package.json里通常会有这么一组：

{ "scripts": { "db:migrate": "node scripts/migrate.js", "db:seed": "node scripts/seed.js --env=local", "db:reset": "node scripts/reset.js", "mock": "node mock/server.js" } }

这里用group:action的命名方式（db是分组，migrate是动作），好处是语义一眼能看懂，而且脚本多了之后还能用通配符批量操作。比如npm-run-all可以一次跑所有db:*脚本。

为什么这些javascript文件不直接node scripts/migrate.js运行，非要绕一层scripts？因为真实场景里这些命令往往还带着额外的环境变量或参数，比如--env=local、NODE_ENV=development，放进scripts里，整个命令就固化了。另外，当团队用不同操作系统时，写在scripts里还能统一通过cross-env来抹平差异，这个下面会专门讲。

2.4 部署发布与运维衔接

部署发布环节，scripts的作用就更明显了。很多云平台、容器平台默认的启动命令就是npm start，或者要求你提供一个build命令。所以无论你用什么框架，我都建议把build和start这两个名字保住。

一个典型的部署配置：

{ "scripts": { "build:prod": "cross-env NODE_ENV=production rimraf dist && vite build", "predeploy": "npm run build:prod", "deploy": "node scripts/deploy.js", "postdeploy": "node scripts/healthcheck.js", "start": "node server/index.js" } }

执行npm run deploy的时候，因为存在predeploy，npm会自动先跑构建，然后才执行真正的deploy脚本，之后自动跑去postdeploy做健康检查。等于你一条命令完成了“构建+发布+验证”三件事。

这里给新手提个醒：start不要随便改名，很多部署平台的默认启动流程就是npm start。build同理，平台会试探性地执行npm run build。如果你把这两个名字改掉了，部署平台配置文件和CI流程都得跟着改，无缘无故增加沟通成本。

2.5 别忽略typecheck和工具类脚本

除了上面这些，我还会把很多“不常用但需要统一”的工具类命令收进scripts。比如TypeScript项目的类型检查：

{ "scripts": { "typecheck": "tsc --noEmit", "storybook": "storybook dev -p 6006", "build-storybook": "storybook build", "gen:icons": "node scripts/gen-icons.js" } }

typecheck这个脚本尤其值得养成习惯。很多项目把tsc --noEmit这条命令写在文档里，大家全凭自觉，结果就是有人跑了有人没跑，CI里被类型错误卡住的概率极高。把它放进scripts后，加上一条npm run typecheck的预检步骤，团队执行成本大幅下降。工具类脚本尽量避免让开发者记“复杂命令+参数”，全部收口到scripts里，这才是工程化的最小单元。

3. npm run背后到底做了什么

3.1 自动加PATH：node_modules/.bin的秘密

很多人第一次疑惑的是：我在项目里npm install vite，没有用-g全局安装，为什么scripts里写vite build就能跑？换成直接在终端敲vite build，往往又报command not found。这个区别的根源，在于npm run命令执行时做了一件隐蔽的事：自动把当前项目下的node_modules/.bin目录加入PATH环境变量。

理解了这一点，很多现象就解释得通了。scripts里的命令，本质上是在一个“额外叠加了项目本地bin目录”的临时shell里执行的。所以本地安装的任何带有bin字段的依赖包，它的可执行文件都能在这个shell里被直接找到。你可以在scripts里临时加一个echo命令来验证，比如：

{ "scripts": { "debug-path": "echo $PATH" } }

在macOS/Linux上跑npm run debug-path，能看到node_modules/.bin被放在了PATH的最前面。

以前我很长一段时间直接手动敲node_modules/.bin/webpack这样的全路径命令，后来才意识到，npm run不仅帮我省了敲路径的力气，还保证了用的一定是本地的、与package-lock.json锁定版本一致的工具，而不是机器上装的那个全局版本。这也解释了为什么团队成员应该在项目里本地安装CLI工具，而不是各自全局安装不同版本。

3.2 参数传递：--分隔符的正确用法

前面在2.2里提过--的用法，这里从执行层面再说透一点。当你执行npm run test -- --watch时，npm解析到--之后，会把它后面的字符串全部拼接进原本的scripts命令末尾，最后实际得到的是vitest run --watch。注意参数只能拼在末尾，没法插到中间某个位置。如果你的工具对参数位置很敏感，比如“启动时先接选项再接文件路径”，那就要在scripts设计时预先想好占位，否则就需要借助环境变量或者工具本身的配置文件来间接实现。

另外，npm在运行你的scripts时还会自动注入一批以npm_package_为前缀的环境变量。比如package.json里的name是my-project，那么脚本里的process.env.npm_package_name就是my-project。你在自己写的node脚本里可以直接读取这些变量。我写过不少部署脚本，就用npm_package_version去拼发布包的版本号，不用再手动维护一个版本变量，效果很稳。

3.3 跨平台兼容：Windows和macOS/Linux的差异

这是跨平台项目里最让人头疼的部分。如果你的团队成员里有Windows用户，scripts里的命令就不能只按bash的语法来写。最典型的差异有两处，第一是环境变量赋值：

# macOS/Linux "NODE_ENV=production vite build" # Windows cmd "set NODE_ENV=production&& vite build"

这里直接写NODE_ENV=production，在Windows的cmd里会直接报错。解决办法就是引入cross-env：

{ "scripts": { "build:prod": "cross-env NODE_ENV=production vite build" } }

cross-env会先把你声明的环境变量翻译成各平台能识别的写法，再去执行后面的命令，跨平台一行脚本立刻变老实。

第二个高频差异是文件操作命令：bash里的rm -rf在cmd里不存在，Unix的mkdir -p、cp -r同理。我建议这种文件操作尽量用Node生态的跨平台工具，比如rimraf（替代rm -rf）、copyfiles或cpx（替代cp），或者干脆用shx，它把常用的Unix命令都封装成了跨平台可用的版本。

还有一个小细节：在scripts里尽量避免使用&字符。你想让两个命令并行跑，在bash里是vite & node server，在cmd里含义完全不同，而且很容易引发难以排查的奇怪问题。多任务并行的问题见后面讲concurrently的部分。

3.4 npx、npm run、直接敲命令三者怎么选

这里再帮你把三个容易混淆的执行方式理清楚。

• 直接在终端敲命令，比如vite：命令解释器只会在当前PATH里找vite，如果vite没有全局安装，大概率command not found。
• npm run dev：等价于在临时shell里执行scripts里dev对应那条命令，此时node_modules/.bin已被加入PATH，所以本地依赖里的工具优先可用。
• npx vite：npx会先在当前项目的node_modules/.bin里查找vite，找不到时它会询问是否临时下载一个包来执行。npx更擅长解决“我没有安装某工具，只想临时用它一次”的场景，比如npx create-vite这种脚手架初始化。

你还可以通过npm config set script-shell来指定scripts默认使用的shell，比如在Windows上把它设为Git Bash的路径。我个人建议Windows用户装上Git Bash，然后统一把script-shell指过去，很多引号和&&的问题会好受很多。不过要注意，改配置只影响你自己，团队成员如果没改，行为就不一致，所以跨平台的写法仍是第一位的，配置优化只是辅助。

4. 从零设计一份高可用scripts清单

4.1 先梳理项目生命周期再动手

我给人review过不少项目的package.json，发现scripts设计得好不好，和项目能不能顺畅协作高度相关。其实设计思路非常简单：先把项目生命周期里所有要操作的事情列出来，然后决定每个人该用什么命令触达它们。

我的清单通常是这样的：

• 安装与准备：npm install之外，可能还要跑一次postinstall，或者一键完成依赖安装和.env复制。
• 本地开发：dev，以及配套的dev:server、dev:client。
• 质量检查：lint、lint:fix、format、typecheck、test、test:watch。
• 构建产物：build、build:prod、build:analyze。
• 部署运维：deploy、logs、rollback。
• 杂项工具：db:migrate、db:seed、gen:icon、storybook。

命名上，我的习惯是低频场景用group:action，比如db:migrate；核心高频命令直接用短词，比如dev、build、test。短词和冒号组合混用是当前生态默认，不会造成理解负担。

这里想强调一点：dev、build、test、lint这四个名字，没有重大理由别改。它们已经成了整个前端生态的通用语言，不管谁来项目，一看到这四个key就知道项目怎么运转。改成一个项目内部喜欢的花名，表面看起来有个性，实际是增加所有参与者的认知成本。

4.2 用npm-run-all和concurrently处理多任务

本地开发时经常需要同时启动多个服务，比如后端服务、前端dev server、mock服务。直接在scripts里用&&连接，会让前一个一直占用终端，后一个根本没机会执行；用&连接又绕回跨平台兼容性的坑。这时候用专门的工具更稳。

推荐两种：npm-run-all和concurrently。npm-run-all的优势是支持通配符和清晰的串并行控制：

{ "scripts": { "dev": "npm-run-all --parallel dev:*", "dev:server": "node server/index.js", "dev:client": "vite --host 0.0.0.0", "dev:mock": "node mock/server.js" } }

跑npm run dev时，它会同时启动dev:server、dev:client、dev:mock三个进程，任何一个进程退出，它都会默认把整个任务终止，避免留下没人管的孤儿进程。concurrently的写法则更直观，适合进程数量固定的场景：

{ "scripts": { "dev": "concurrently -k -n server,client,mock -c blue,green,yellow \"node server/index.js\" \"vite\" \"node mock/server.js\"" } }

-k参数表示一个进程挂了就杀掉其他进程，-n是给每个进程取名字，-c是颜色，日志一眼能分清是哪条输出。

需要提醒的是：并行工具更适合本地开发，在CI或生产环境里，多数情况下还是建议串行执行。并行跑test和lint虽然更快，但一条失败你要能及时发现，不然部署流水线会被“部分成功”的假象坑掉。

4.3 一份可直接抄的Vue项目scripts模板

说了这么多，最后给一份可以直接抄作业的前端项目scripts模板，以Vue 3 + Vite为例：

{ "scripts": { "dev": "vite --host 0.0.0.0", "build": "npm run typecheck && npm run lint && rimraf dist && vite build", "build:prod": "cross-env NODE_ENV=production npm run build", "preview": "vite preview --host 0.0.0.0", "test": "vitest run", "test:watch": "vitest", "lint": "eslint . --max-warnings=0", "lint:fix": "eslint . --fix", "format": "prettier --write \"src/**/*.{ts,vue,css}\"", "typecheck": "vue-tsc --noEmit", "db:migrate": "node scripts/migrate.js", "db:seed": "node scripts/seed.js", "predeploy": "npm run build:prod", "deploy": "node scripts/deploy.js", "storybook": "storybook dev -p 6006" } }

注意build这一条：我故意让它串联了typecheck和lint。因为构建是最能暴露问题的聚合点，任何人准备出包时都会自动触达这一串检查；一旦检查失败，vite build根本不会启动，从源头拦住坏代码。rimraf dist出现在构建前，是为了保证产物目录永远是干净构建。predeploy配合deploy的用法前面讲过，这里不重复。

这份模板是按“一条构建会自动带出检查”的思路设计的，团队用了大半年效果一直很稳定。你完全可以基于自己项目的工具链微调，但结构思路可以照搬。

5. 常见问题与排查实录

5.1 command not found让你怀疑人生的三个原因

这是出现频率最高的报错，没有之一。明明package.json里写得好好的，一跑npm run dev就command not found。我遇到过的情况基本可以归成三类。

第一类：项目依赖根本没装。刚clone下来的仓库，直接跑npm run dev，此时node_modules还不存在，node_modules/.bin里自然也什么都没有。先跑npm install再执行，基本能解决。

第二类：装了依赖但shell环境不对。如果你用nvm之类的工具管理Node版本，切换到另一个Node版本后，之前安装的依赖可能不再位于当前应用的PATH里。检查一下node_modules/.bin里有没有对应的可执行文件，这个方法可以一击命中：

ls node_modules/.bin | grep vite

有这个文件，说明装好了，报错就是环境变量问题；没有这个文件，说明依赖没装对，回到第一步。

第三类：执行目录不对。在monorepo里，这是一个重灾区。你站在仓库根目录跑子项目的scripts，npm根本找不到子项目里的node_modules/.bin，自然报错。解决方案是先cd到对应子包目录，或者使用npm workspace的--workspace参数。

我个人的排查习惯是：先看node_modules/.bin，再看当前目录，最后才怀疑配置。顺序反过来，很容易绕远路。

5.2 Windows上跑脚本满屏诡异的报错

Windows上跑scripts的报错，真的是千奇百怪。最常见的两种：一是NODE_ENV=production开头，直接提示“NODE_ENV不是内部或外部命令”；二是脚本里用了rm -rf或者&，cmd解析出来完全是另一个意思。

遇到这类问题，我的建议很直接：先检查项目里是否所有环境变量赋值都用cross-env包了；再检查文件删除、复制操作是否用了rimraf、copyfiles这些跨平台替代。如果这两点都做到了，Windows下的报错会少一大半。剩下一小半，多半是引号的锅。在cmd里，双引号和单引号的行为和bash不一样，prettier --write \"src/**/*.ts\"这种带通配符和引号的写法，在cmd里有概率不会被正确解析。可以考虑改用glob参数或者其他不会依赖引号的写法。

如果你实在不想被这些差异折磨，我的土办法是：Windows开发者安装Git Bash，然后把npm的script-shell指定到bash.exe路径：

npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe"

这样scripts里所有命令都会交给bash执行，跨平台写法兼容度瞬间提高。但记得这只影响个人机器，项目里该用cross-env的地方还是得用，否则没装Git Bash的同事依然会被坑。

5.3 本地好好的，CI里突然挂了

本地跑npm run build成功，推到CI上第一条构建就挂了，这种“换环境就翻车”的问题最让人恼火。除了常见的依赖锁文件没提交，还有一个很容易被忽略的因素：CI通常会额外注入一堆环境变量，比如CI=true。很多工具在这个环境下会改变行为，例如部分测试框架会默认关闭watch模式、部分日志库会改成无颜色输出。你的脚本如果没考虑到这些，行为就会和本地不一致。

排查的办法是尽量在本地模拟CI环境。以macOS/Linux为例：

CI=true NODE_ENV=production npm run build

如果这样能复现问题，那就快速定位了。再看脚本里有没有依赖某个本地才有的全局工具、有没有读取本地配置文件，这些在干净的CI环境里都很可能不存在。还有一点常被忽略：CI里执行npm install时，某些流水线会传--production参数，那devDependencies就不会被安装，而scripts里用到的工具比如vite、eslint恰恰都安装在devDependencies里。结果就是本地能跑，CI直接command not found。

碰到CI问题，先把npm install的参数查清楚，再去看环境变量，最后才怀疑脚本本身。这个排查顺序在绝大多数情况下都能少走弯路。

5.4 端口占用和残留进程处理

开发中最常见的运行时问题是端口占用。你本地起了一个dev server，没正常退出，再跑一次dev脚本，Vite直接报“Port 5173 is already in use”。npm官方其实也试过帮我们自动换端口，但不能总是依赖它，因为有些场景比如代理配置、回调地址白名单，端口是固定的。

我自己会针对不同操作系统用不同的排查命令。macOS/Linux那边是：

lsof -i :5173 kill -9 PID

Windows那边是：

netstat -ano | findstr :5173 taskkill /F /PID 你的PID

如果你觉得每次都手动查很烦，可以装一个kill-port，在scripts里提供一条清理命令：

{ "scripts": { "kill:port": "kill-port 5173 4173" } }

不过我一般不太建议把kill命令默认挂在dev前面，因为它会无条件杀掉同名端口的进程，万一那是一个同事正在用的服务，就误伤了。有事手动跑一下就好，别默认执行。

还有一个残留进程的来源：脚本里用了&让命令后台执行，结果父进程退了，子进程还在后台跑。这也是为什么我前面强调并行任务用concurrently这类工具，因为它能帮你统一管理子进程，退出时一起清掉。裸写&的后台进程，一旦忘了手动清理，端口占用是迟早的事。

最后分享一条我自己在实际项目里一直坚持的小原则：scripts不是写给别人看的文档，更像是项目的一个操作契约。凡是团队成员需要重复执行的长命令，都应收进这里，并保证名字尽量符合直觉；凡是可能因为环境差异翻车的命令，都应优先考虑跨平台写法。你在这上面多花十分钟，团队在未来一年就能少踩无数个坑。

如果你正在维护一个自己负责的项目，建议现在就打开package.json，把里面所有scripts从头扫一遍，看看有没有漏网的长命令没有收进来，有没有Windows同事会踩的坑。改完之后跑一遍全流程，你会发现项目管理这件事，很多时候就是从这一小块配置开始的。