企业官网建设流程全解析

如果你已经能在 Node.js 里写出能跑的接口，能在本地起服务、连数据库，甚至已经交付过一两个小型项目，那大概率会碰到一种很微妙的状态：功能都能写出来，但代码一多就开始乱；加个新需求要翻半天文件；改一个函数，不知道哪里会跟着报错；线上出了异常，只能靠 console.log 续命。这就是典型的第二阶段到第三阶段的过渡期。第三阶段的核心不是学新框架，而是把工程化能力补上，靠规范、工具、自动化同时把代码质量和开发效率拉起来。这篇文章按我自己从“能写”到“能维护”的真实路径，把版本管理、代码规范、测试、日志、生态扩展这些事串起来讲一遍，适合已经有一定 Node 基础、想让项目进入良性循环的开发者。

1. 为什么需要第三阶段：能跑通和能维护是两件事

1.1 第二阶段到第三阶段之间，最常见的失控信号

我见过很多“能跑通”的项目，也接手过不少“一碰就碎”的系统。它们的共同点不是写得烂，而是缺少一套让代码持续变好的机制。典型信号包括：

• 每个接口自己 try/catch，错误处理风格完全不一样，有的返回 500，有的返回字符串，前端对接全靠猜。
• package.json 里全是^开头的依赖，今天能跑，明天依赖一更新，莫名其妙挂了。
• 没有 lint，代码风格靠 review 时候口头说，说了两轮之后大家也懒得改了。
• 测试是 0，改一个公共函数，没人知道会影响多少调用方。
• 代码 review 只是形式，因为 reviewer 根本看不完那么多上下文。

如果你在这个清单里中了三条以上，说明已经不是“会不会写 Node.js”的问题，而是工程化缺位的问题。能跑通，代表程序行为符合预期；能维护，代表团队在持续变化、多人协作的前提下，依然能低成本地保持正确。这两件事之间差着一条完整的工具链和一组约定。

1.2 工程化的本质，是把约定变成工具

有人一听到工程化就想到 Docker、K8s、CI/CD、微服务，觉得门槛很高。其实工程化的本质只有一句话：把“靠人记住的约定”变成“靠工具强制执行的规则”。

拿“提交前跑测试”举例子。你可以在团队规范里写十条“必须跑测试”，但人总会忘；如果你在 Git 钩子里配置好，commit 时测试不通过就提交不了，这条规则就从“建议”变成了“强制”。同样的道理，缩进、引号风格可以靠 prettier 自动格式化，不用让 review 者把时间浪费在讨论“你到底用单引号还是双引号”上。

我自己喜欢用装修做类比：工程化是在墙内铺管线、埋插座，表面上看不到，但住进去之后每个房间都能稳定用电。不铺管线的房子也能住——用插线板嘛，代码也能跑——但用着用着就会跳闸。Node.js 项目进入第三阶段，做的正是“铺管线”这件事。

1.3 生态扩展不是堆依赖，而是为了应对业务复杂度

第三阶段的另一半是“生态扩展”。注意，这句话不是说新出的库你都要接一遍。我看到过太多团队，为了用 NestJS 而引入 NestJS，本来 Express 三百行能写完的内容，硬是拆了六个模块，光理解目录结构就要一下午。这不是扩展生态，这是给自己挖坑。

生态扩展的正确动机是业务复杂度发生了变化：模块越来越多、领域规则越来越复杂、发布节奏越来越高，旧的写法承载不住这种复杂度了，才需要换一种“能接得住复杂度”的方案。所以这个阶段里，比起“用什么新东西”，更重要的是先回答“我现在到底疼在哪”。依赖扩展解决的是“需要什么能力”，框架选型、服务拆分解决的是“这个复杂度该怎么组织”，它们都是为业务服务的，不是用来证明团队很时髦的。

2. 先把地基打稳：Node 版本管理与包管理器选型

2.1 版本管理：nvm、fnm 与“版本不存在”的坑

很多项目最开始只有一个本机 Node，版本是当初安装时随手装的。等团队成员一多，问题就来了：A 用 18，B 用 20，C 用 22，跑出来的行为可能不一样。Node 版本看似是小事，但差异会在生产环境集中爆发，尤其是涉及异步资源、TLS 握手、fetch 行为这些底层变化时。

我个人的习惯是用 nvm，最近也在体验 fnm。nvm 老牌稳定，缺点是每次开新终端要等 shell 加载，稍微有点慢；fnm 用 Rust 写的，响应快，配置好之后几乎无感。二者都支持.nvmrc文件：

nvm install 20 nvm use 20 node -v

在项目根目录写一个.nvmrc，内容写20，这样团队任何成员进入项目后执行nvm use，就能切到统一版本，避免“我本地好的呀”这种经典甩锅。

这里有个高频坑：执行nvm install 24.21.0这类命令时，报错提示node.js v24.21.0 is not yet released or is not available。真实原因通常是这几种：你要装的版本还没正式发布，只有 RC 或者 Nightly 版本；nvm 本地的版本索引太旧，没同步到最新发布信息；或者网络原因无法访问官方源。解决办法也不复杂：

nvm ls-remote

先看远端到底有哪些可用版本，千万别对着搜索引擎里的“最新版”直接装。如果确实需要某个版本节点，但官方源访问不稳定，可以去 npmmirror 的 node 镜像目录确认发布状态。还有一个更稳妥的建议：生产环境老老实实跟着 LTS 走，不要因为想尝鲜就上奇数版本或者刚发布的非稳定版。项目的稳定运行比“我机器上版本最新”重要得多。

顺带提一下 CI 和 Docker 场景。CI 里用官方 setup-node 指定版本即可：

- uses: actions/setup-node@v4 with: node-version: 20

Docker 容器直接FROM node:20-slim，尽量不复用宿主机环境，保证构建环境一致。版本这一层解决之后，很多“换台电脑就挂”的问题会直接消失。

2.2 我为什么从 npm 切到 pnpm

包管理器是工程化的地基之一。早期项目大多用 npm，默认情况下它会把依赖拍平装进一个扁平的 node_modules 里，这带来了一个很隐蔽的问题——幽灵依赖。比如你并没有直接安装 express-session，但因为你间接依赖了它，代码里可能意外地能require('express-session')；某天底层依赖升级，这个包从依赖树里消失了，你的应用就莫名其妙挂了，而排查成本极高。

pnpm 的做法完全不同：它把包内容放在全局统一的内容寻址存储里，然后通过硬链接和软链接来组织 node_modules。项目里只有你真正声明的依赖才能被直接引用，依赖关系变得严格且可预期。磁盘占用也会明显下降，尤其在多个项目共用一个 Node 版本的时候，实测能省下三分之一甚至更多的空间。

切换成本很低。团队统一使用 pnpm 后，基础命令几乎没有学习成本：

pnpm install pnpm add lodash pnpm add -D typescript

唯一的硬性要求是：不要混用包管理器。我踩过很现实的坑——仓库里既有 package-lock.json 又有 pnpm-lock.yaml，有人用 npm 装过依赖后，换个机器用 pnpm install，锁文件冲突，依赖版本漂移，最后花了大半天才定位到一个只在特定环境出现的 bug。现在我的做法是，在仓库 README 和 CI 配置里都明确包管理器，并在 package.json 中用packageManager字段固定版本：

"packageManager": "pnpm@9.15.0"

这样即使用 npm 执行 install，也会收到提示，避免带乱 lockfile。

2.3 用 scripts 把命令规范成团队接口

第三阶段一个容易被忽视的细节，是把常用命令统一收口到npm scripts（pnpm 也兼容）里。每次项目交接，新同事第一件事情是做环境跑通，如果靠口头问来问去，效率极低。用 scripts 把这些约定固化下来，就是给团队提供一个“操作接口”。

我通常会在 package.json 里统一维护这样一组命令：

"scripts": { "dev": "node --watch src/server.js", "start": "node src/server.js", "lint": "eslint .", "format": "prettier --write .", "test": "node --test", "typecheck": "tsc --noEmit" }

当项目不止一个服务时，可以用 concurrently 把多个进程串起来：

"dev": "concurrently \"npm:dev:api\" \"npm:dev:web\""

需要提醒的是，Windows 下双引号嵌套很容易出问题，挂一个cross-env是常规解法。script 本身不复杂，但它背后是“团队入口统一”的思维——每个人不需要记一堆内部命令，只要看 scripts 就能知道这项目怎么跑、怎么测、怎么查类型错误。这也是工程化里成本最低、收益最明显的部分。

3. 代码质量的第一道防线：ESLint、Prettier 与 Git 钩子

3.1 ESLint 从 config 到 flat config

ESLint 在 9.x 版本开始默认使用扁平配置（flat config），主配置文件从.eslintrc变成了eslint.config.js。刚升级的时候我也嫌烦，但用下来之后觉得方向是对的：以前的 .eslintrc 继承链和 overrides 组合容易把人绕晕，现在的数组结构直观很多。

一个最基本的 Node.js 项目配置大概是这样的：

import js from '@eslint/js'; export default [ js.configs.recommended, { rules: { 'no-unused-vars': 'warn', 'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn' } } ];

如果是 TypeScript 项目，可以直接用 typescript-eslint 的组合：

import tseslint from 'typescript-eslint'; export default tseslint.config( js.configs.recommended, ...tseslint.configs.recommended );

我个人的经验是：规则不要一次开太多。有次我接了个新项目，把网上流传的“最强 ESLint 配置”整包粘进去，结果团队所有人第一次 commit 都要面对几千条 error，连门都出不去，最后只能把 lint 悄悄关掉。工程化的前提是让工具能跑进日常流程，而不是制造障碍。正确做法是先开 recommended 级别，让机器盯住未使用变量、未定义变量、明显 bug 这类硬伤，然后再根据团队需要逐步增加规则。

ESLint 的价值不只是“风格统一”，它更重要的是在编译之前帮我们挡掉一部分低级错误。比如变量明明声明了却没用，比如误写了全局变量，这些不一定是肉眼能快速发现的，但机器可以。规则一旦落地，代码审查的精力就可以从这种琐碎问题上解放出来。

3.2 Prettier 和 ESLint 的分工，别用插件强行合并

早期有个很流行的做法：用 eslint-plugin-prettier 把 Prettier 当作 ESLint 的一条规则来跑，这样执行一次 eslint 就能同时完成格式检查。我也这么干过，但后来在稍大一点的项目里明显感觉到 lint 速度变慢，而且两边职责重叠，经常出现“eslint 说改格式，prettier 又说改格式”的循环。

现在的推荐做法是明确分工：

• ESLint 管逻辑问题、潜在 bug、代码规范类规则。
• Prettier 管格式问题：缩进、引号、分号、换行。
• 用 eslint-config-prettier 关掉 ESLint 里和 Prettier 冲突的格式规则。

Prettier 本身配置很轻：

{ "singleQuote": true, "semi": true, "trailingComma": "es5" }

重点其实不在具体选哪套风格，而在于格式问题不应该成为 code review 的讨论对象。没有 Prettier 的时候，两个同事能因为“单引号还是双引号”争论十分钟；有了 Prettier 之后，机器自动搞定，review 只聊架构、逻辑、边界条件，效率完全不是一个量级。

3.3 Husky 与 lint-staged：把检查卡在提交前

工具链再好，如果和触发时机脱节，一样会偷懒失效。所以我会在 Git 钩子这一层把 lint 和格式化塞进提交流程，用的工具就是 husky 配合 lint-staged。

安装配置很简单：

npm install -D husky lint-staged npm pkg set scripts.prepare="husky" npm run prepare npx husky add .husky/pre-commit "npx lint-staged"

然后在 package.json 里配置 lint-staged，只处理暂存区的文件：

"lint-staged": { "*.{js,ts}": ["eslint --fix", "prettier --write"], "*.{json,md}": ["prettier --write"] }

我特别强调“只处理暂存区文件”这一点。全量 lint 在项目几千个文件的时候要跑很久，每次 commit 之前等半分钟，人就不愿意用了；lint-staged 只检查本次要提交的文件，速度飞快，才能真正嵌进日常流程。

再往前一步，可以在 pre-push 钩子里跑一遍测试：

npx husky add .husky/pre-push "npm test"

这是本地反馈和 CI 之间的一层缓冲：push 之前先确认基础测试没问题，CI 里则跑更完整的检查包括集成测试、类型检查、构建验证。有人觉得“反正 CI 会查，本地不用重复”，我的看法相反——CI 是底线，它的反馈周期长；本地钩子是即时反馈，能把问题挡在离开你电脑之前。两件事互相补充，不能互相替代。

有个细节容易踩坑：husky 老版本升级后，钩子文件路径和实现变了，一些旧项目会出现在 Windows 上钩子不生效的情况。遇到这种问题先确认 git 是否启用了 core.hooksPath，必要时直接重新执行npx husky init重新生成钩子脚本。

4. TypeScript 与测试体系：让错误在发布前暴露

4.1 渐进式接入 TypeScript 的正确姿势

第三阶段里我会强烈建议把 TypeScript 纳入体系，尤其是项目进入多人协作阶段之后。TypeScript 本身不是银弹，但它在接口约束、重构安全性、代码自文档化这三个方面带来的收益非常明显：当你把“改一个字段要看所有调用方”变成“编译器帮你找出所有报错”，重构成本会大幅下降。

存量 JavaScript 项目不需要推倒重来。渐进式接入是我验证过最稳的路线：新文件或大改文件用 TS，老文件继续 JS 跑，通过 tsconfig 的 allowJs 和 checkJs 让两者共存。只要 package.json 里"type": "module"处理好，TS 编译产物能正常加载。一份够用的 tsconfig 大概是这样的：

{ "compilerOptions": { "target": "ES2022", "module": "NodeNext", "strict": true, "esModuleInterop": true, "skipLibCheck": true } }

对于新项目，我建议直接开"strict": true，越早承受类型约束，代码收益越大。存量项目如果一下子开 strict 会冒出一堆历史类型错误，团队很容易放弃，所以更实际的做法是先不开，在需要关注的文件里逐步补上类型，配合// @ts-check让编译器逐个文件介入。

这里最需要警惕的是any泛滥。开了 TypeScript 却到处any，等于把编译器当成摆设，反而增加了噪音。我的经验是在 lint 规则里把显式 any 设为 warn，让大家写类型像写注释一样自然，而不是把它当成一种负担。

4.2 用最小闭环把单测和接口测试跑起来

测试是工程化里最容易“口头上重视、行动上忽略”的部分。很多理由我都能理解——业务忙、排期紧、改需求频繁。但作为过来人，我建议哪怕只有一个最小的测试闭环，也要先建立起来。

现在 Node 内置了node:test，搭配 assert 模块，对小型项目足够用。接口测试用 supertest 非常顺手：

import { test } from 'node:test'; import assert from 'node:assert/strict'; import request from 'supertest'; import { createApp } from '../src/app.js'; test('GET /health 返回 ok', async () => { const app = createApp(); const res = await request(app).get('/health'); assert.equal(res.statusCode, 200); });

如果项目已经用了 Jest 或者 Vitest，也没必要强行切换，选型原则就一条：团队能持续维护的运行方式，就是最好的测试框架。Jest 生态成熟，Vitest 对 TS 开发体验更好，node:test 则省掉一层依赖。关键是先让“测试能跑、且能在 CI 里跑”这件事发生。

数据库相关的测试，本地尽量不要去连共享的开发库。用 Docker 起一个临时数据库实例，测试结束直接销毁，干净利落。之前有个项目因为测试连了同一个开发库，每次跑测试都会被别人的数据干扰，后来改成 docker-compose 单独起库，这类“flaky test”基本绝迹。

4.3 覆盖率是参考，关键路径才是底线

关于覆盖率，我的态度是：数字要有，但别迷信。有些团队把覆盖率目标定到 90%，但我见过为了凑这个数字给所有 getter/setter 写测试的项目，既浪费时间又创造不了价值。覆盖率指标的意义在于发现“完全没被测试触碰过的模块”，而不是逼着大家给每行代码盖章。

真正的底线是关键路径必须有测试。我一般会优先照顾这几类代码：

• 支付、订单这类直接和钱挂钩的流程。
• 鉴权、权限判断、登录态验证。
• 对接第三方 API 的重试、超时、异常处理逻辑。
• 核心业务工具函数，比如优惠金额计算、日期解析、状态机流转。

这些模块一旦出问题，影响是连锁的。把它们用测试锁住，其他部分哪怕测试少一点，系统整体风险也在可控范围内。UI 层端到端测试可以做，但不是第三阶段的优先级，先让单元测试和接口测试形成闭环，再把覆盖面逐步铺开。

5. 日志、错误处理与本地调试：线上问题不靠猜

5.1 先分清“谁能处理这个错误”

工程化做到一定程度，你会发现代码里最脏的东西往往不是逻辑，而是错误处理。每个人写接口的时候都按自己的理解处理错误，有的吞掉、有的抛字符串、有的返回 200 但 body 里塞一个 error flag，前端对接的时候全靠人肉翻代码。

我的建议是在项目里先建立一种分类思维：这个错误是调用方能处理的，还是只能记录的。

• 可预期错误：参数校验失败、业务规则不满足、资源不存在。这类错误应当明确返回结构化信息，包括状态码、错误码、可读信息。
• 不可预期错误：数据库连接失败、第三方服务超时、代码运行时异常。这类错误需要被完整记录下来，同时对外返回统一的 500，不要让内部堆栈直接暴露给客户端。

在 Express 这类框架里，异步错误最容易被吞。Express 4 不会自动捕获 async handler 里抛出的 Promise rejection，所以我一般会包一层：

const wrap = (fn) => (req, res, next) => fn(req, res, next).catch(next);

然后在全局错误中间件里统一处理。还要留意process.on('unhandledRejection')，有些人喜欢在这里只 console.log 一下然后继续运行，看起来“很稳”，实际上应用状态可能已经坏了。更稳妥的做法是记录完整错误信息后，让进程退出，交给 PM2 或 Docker 的 restart 策略拉起新实例。反正失败状态比“带病运行”好恢复，至少不会让请求拿到过期的状态。

5.2 结构化日志：从 console.log 到 pino

console.log 在本地调试很好用，但它不是日志方案。线上日志如果把所有信息打成一个字符串，后续检索、聚合、关联都会非常痛苦。我后来逐步切到了结构化日志，也就是输出 JSON 格式的日志，库用 pino 和 winston 都很常见。

一个最小化的 pino 配置：

import pino from 'pino'; const logger = pino({ level: process.env.LOG_LEVEL || 'info', base: { service: 'user-api' } }); logger.info({ userId, action: 'login_success', costMs: 32 }, 'user login');

结构化日志的优势是：每条日志自带 service、level、timestamp、上下文字段，日志平台可以直接按字段过滤、聚合，而不是靠正则去字符串里抠信息。我在项目里还会做一件事：在请求入口中间件生成一个 requestId，用crypto.randomUUID()存到 req 上，然后后续所有日志都带上它。这样用户报“我下单选不了”，我搜 requestId，就能拿到这次请求在经过的每个服务、每段代码里的日志，排查效率提升非常明显。

还要定一个规矩：日志里不打敏感字段，比如密码明文、token、身份证号。日志一旦进入第三方平台，就是高风险的泄露点，在打点之前过一遍脱敏是必须的习惯。

5.3 sourcemap 与生产环境堆栈还原

这个坑很隐蔽，等你在生产日志里看到一堆at async fn (dist/index.js:1:123456)的时候就知道痛了。TS 编译后、代码压缩后，堆栈信息丢掉了源码可读性，靠这种堆栈没法定位问题。

解决方案是发布时带上 sourcemap 文件，部署时让它能对上源码，错误上报工具（比如 Sentry）就能自动还原出错的具体文件行和函数。没有接入上报工具的情况下，也可以把 map 文件放在单独的位置，排查异常时手动映射。

这里有个安全细节：不要把 sourcemap 直接暴露到公开可访问的静态目录下。Sourcemap 会把完整源码映射出来，等于主动泄露源码。正确的做法是放到内部存储，或者只对具有调试权限的环境开放，配合访问控制使用。这是工程化里容易忽视但影响很大的一个点。

6. 生态扩展的正确姿势：框架选型、服务拆分与 AI 辅助评审

6.1 框架选型：Express、Fastify 与 NestJS 怎么选

框架选型是技术社区永恒话题，每次都能吵几百楼。我在实际选型时会先做一道选择题：我的项目需要多少结构约束。

三个主流选项放一起对比：

三大框架现在都还在快速演进，比如 Express 5.x 也解决了部分异步错误处理问题；Fastify 的序列化能力和插件体系非常现代；NestJS 则把依赖注入、装饰器、模块划分一股脑带给你。

我的建议是：如果团队之前一直用 Express，业务规模也没到失控的地步，没必要为了“先进”而重写。但如果你已经预见到业务会持续变复杂、模块边界越来越清晰，那投入 NestJS 的学习成本是值得的，它会逼着你按结构组织代码。选型没有绝对对错，只有“当前阶段匹配不匹配”。最怕的是团队的能力和框架的复杂度不匹配：四个人没写过 NestJS，却要先上 NestJS，前三个月效率会非常难看。

6.2 拆服务、上队列，什么时机最合理

微服务不是第三个阶段一定要做的事，但它经常出现在大家的待办清单里。我见过最夸张的一个项目是“一个用户模块拆四个服务”，每个服务里就两张表，服务间调用链路超过五跳，线上排查问题要翻四五个服务的日志才能拼出完整图景。这不是架构升级，是自找麻烦。

拆服务的前提通常有三个：

• 团队人数足够多，模块之间可以有自己的 owner 和发布节奏。
• 模块之间有明确的领域边界，比如支付、风控、推荐这类天然独立的能力。
• 数据库归属独立之后，可以降低耦合，而不是为了拆而拆。

在这个阶段，我更推荐先把“模块边界”画好：在单体代码里用文件夹、分层、显式接口模拟服务边界。等单体内部的边界开始反复跨越、部署频率互相冲突，再把它物理隔离成服务，成功率会高很多。

消息队列也是一样。很多人一说异步就上了 Kafka，其实单机队列 BullMQ 基于 Redis 已经能覆盖大量轻量异步场景：延迟任务、重试队列、进度通知。先用最符合团队维护能力的方案，等吞吐量、持久化策略、跨语言消费这些需求真正出现，再升级到更重的消息系统。能拿数据库事务解决的问题，不要急着交给队列。

6.3 AI 辅助代码评审：能过第一道筛，但不能替代人

这两年代码评审领域最大的变化，是 AI 开始介入。我记得在评测报告里看到过一个数据，华为云码道检视修复智能体这类产品的召回率能做到 91.3% 左右，对静态缺陷、安全弱点、规范问题的识别能力，已经明显高于人工抽检的平均水平。这个方向我很认可：AI 不会累，不会因为 review 到第三十个文件就敷衍，适合放在提交前后做第一道筛子。

但我不建议直接把评审决策权完全交给 AI。核心原因是：代码评审的目标不只是找 bug，还包括理解业务语义、评估设计合理性、发现异常边界条件。AI 在“这段代码和外部系统交互时的业务假设”这类问题上仍然不能保准。所以更合理的分工是：AI 先扫一遍明显问题，把低级错误、规范冲突挡在门外；人的精力集中在架构、上下文、性能预期这些机器还不擅长的地方。

现在不少 DevOps 平台已经支持在 PR 阶段自动跑 AI 检视，标注出可疑代码行并给出修复建议。我比较推荐的做法是把 AI 检视结果当作工程化数据的一部分：某个规则频繁触发，说明团队的共性问题在这里，可以沉淀到自定义 ESLint 规则里；某个安全缺陷反复出现，则要安排针对性的培训。AI 辅助评审加上人工兜底，能让质量防线更厚，但前提是“人没有完全躺平”。

我这些年带项目有一条主线：先立章程，再补工具，最后才谈扩展。工程化不是一天建成的，也不是工具越多越好。我自己比较推崇每个阶段只解决当前最痛的问题——先是版本和依赖管住，再是 lint 和格式管住，然后是测试和错误处理，等这一套转起来，新业务进来不慌，线上出问题能快速定位，这时候你才有余力去考虑要不要拆分、要不要换框架。如果你正卡在“代码能跑但不敢改”的阶段，建议从今天开始先加 lint，再补一条核心路径的测试，一周之后你会明显感觉到开发体验的变化。