★ FEATURED ARTICLE 如果你已经能在 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 用 18B 用 20C 用 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-nodev4 with: node-version: 20Docker 容器直接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: pnpm9.15.0这样即使用 npm 执行 install也会收到提示避免带乱 lockfile。2.3 用 scripts 把命令规范成团队接口第三阶段一个容易被忽视的细节是把常用命令统一收口到npm scriptspnpm 也兼容里。每次项目交接新同事第一件事情是做环境跑通如果靠口头问来问去效率极低。用 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 configESLint 在 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.preparehusky 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 到 pinoconsole.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 怎么选框架选型是技术社区永恒话题每次都能吵几百楼。我在实际选型时会先做一道选择题我的项目需要多少结构约束。三个主流选项放一起对比维度ExpressFastifyNestJS学习门槛低中较高生态成熟度非常高较高中高结构约束自由无强制插件化有建议规范模块化、依赖注入强制性强TypeScript 支持一般需自行配置好schema 验证强原生支持适用场景小型服务、原型、团队熟悉高性能 API、对性能敏感中大型项目、复杂领域模型三大框架现在都还在快速演进比如 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再补一条核心路径的测试一周之后你会明显感觉到开发体验的变化。
阅读完成 · 觉得有帮助？
