上个月帮一个做电商后端的朋友看代码,他拍着桌子跟我说:“我 TypeScript 全用上了,strict 也开了,怎么线上还天天因为字段对不上报错?”
我把日志拉出来一看,哭笑不得。数据库里某条订单记录的用户字段叫 user_name,代码里却按 username 读;接口返回的 total 后端传字符串,前端当数字算了三遍。这些错误,编译器压根没拦,因为两处代码各自都没“错”——错在它们之间没人管。
这其实就是 TypeScript 在 Node.js 项目里最大的坑:类型只在你明确画边界的地方才管用,边界之间全是黑话对暗号的野路子。这篇文章不堆概念,就把这几年踩出来的五个最值钱的经验摊开讲。
先想清楚:TS 在 Node 后端里到底替你干了什么
很多人引入 TypeScript 的理由是“写错了编辑器会报红”,这理解太浅了。在后端场景里,TypeScript 真正的价值是当全项目的数据形状说明书。
后端代码的特点是:数据进进出出特别多。数据库里一条记录、HTTP 请求体一个 JSON、第三方 API 一个响应——这些东西全是“运行时才有真相”。你 res.json() 拿到的东西,编译器其实一无所知,全靠你提前告诉它。
所以正确的心法是:对外部数据,永远别信,先验明正身再入库。可以用 Zod 这类 schema 校验库,把请求体先过一道筛子:
import { z } from 'zod';
const orderSchema = z.object({
user_name: z.string().min(1),
total: z.coerce.number().min(0), // 字符串自动转数字,转不了直接报错
});
// 校验通过,data 的类型自动推出来,后面写错属性编辑器立刻标红
const data = orderSchema.parse(req.body);
文章开头那个 user_name 对不上 username 的坑,用 schema 定义一次、前后端共用一份,就永远不可能再发生。类型校验是静态的,schema 校验是运行时的,两个都用上,才算把门真正关上。
2025 之后的真相:Node 已经能“裸跑” TypeScript 了
这是这两年变化最大的一点,很多人还没更新认知。
Node.js 从 22.6 版本开始实验性的类型剥离(type stripping),到 24 版本已经稳定。说的直白点:你的 Node 现在可以直接执行 .ts 文件,不需要 tsc 转译,也不需要 ts-node。
原理也简单——TypeScript 绝大多数语法是纯“标注”,比如 : string、接口定义,运行时直接删掉就行,这个过程官方叫 erasableSyntaxOnly。
本地跑脚本、写个 CLI 工具、起个小服务,现在可以这么写:
{
"scripts": {
"dev": "node --experimental-strip-types src/index.ts",
"build": "tsc -p tsconfig.build.json"
}
}
但别急,有两点限制必须说清:一是它只剥类型、不做任何类型检查,所以 CI 里那行 tsc --noEmit 千万不能省——类型检查是开发期的事,跑代码归跑代码;二是不支持枚举、命名空间这类带运行时行为的旧语法,新项目就别碰它们了。
我自己的分工是:开发用 tsx 热重载,CI 用 tsc --noEmit 把关,生产部署照旧 tsc 编译出 JS 再跑。新东西尝鲜可以,关键链路上别赌。
tsconfig 别照抄模板,这四个选项先过一遍
很多人项目出问题,根源就在一份从别处抄来的 tsconfig 里。这四个选项,建议你打开配置文件逐条问自己一遍。
strict: true 没开,等于 TS 只帮你捡了个零头。这个开关下面藏着十几项更严格的检查,undefined 漏判、隐式 any 这些后端最容易翻车的点全在里面。新项目没有理由不开;老项目开不起来也别硬上,逐个选项对着修。
module: "CommonJS" 还在用的话,说明项目还停在 Node 16 时代。新项目统一 module: "NodeNext",跟 Node 的模块解析规则完全对齐,require 和 import 混用的怪问题能少一多半。
skipLibCheck: true 建议开着。它会跳过 node_modules 里 .d.ts 文件的类型检查,避免你为一个第三方库的类型声明错误干瞪眼——编译提速明显,还不影响你自己代码的严格度。
最后一个,tsconfig.json 里同时装 "include": ["src"] 和 "outDir": "dist",却忘了排除测试文件,结果把测试代码也编进了产物。建议拆成 tsconfig.json(编辑器用)+ tsconfig.build.json(编译用)两份,各行其是。
错误处理:后端项目里最见功力的地方
Express 5 已经原生支持 Promise rejection 自动转发给错误中间件了,如果你在 2026 年还在写每个路由外面套 try-catch 再手动 next(err),那是时候精简了。现在的推荐结构是:
配合一个统一的错误中间件,按错误类型映射状态码,把堆栈只记进服务端日志,给前端返回固定结构:
app.use((err: unknown, req, res, next) => {
if (err instanceof HttpError) {
return res.status(err.status).json({ code: err.code, message: err.message });
}
logger.error(err);
return res.status(500).json({ code: 'INTERNAL_ERROR', message: '服务器开小差了' });
});
这里还有个 TS 特有的细节:Express 的 err 参数官方类型是 any,传到中间件里第一件事就是收窄成 unknown 再判别,别图省事直接用——否则你前面在请求体上费的那些校验功夫,最后全漏在了错误对象上。
往后看:类型正在变成全栈团队的对讲机
两个趋势值得现在就知道。
一个是 tRPC 这类端到端类型方案在快速普及。以前前后端对接要维护接口文档,文档过时了也没人发现;现在一份类型定义,前端调用函数时参数和返回值自动跟随后端变化,接口对不上的情况在编译期就现形。用社区的话说,这就像从写信改成了打电话——沟通成本几乎归零。
另一个是工具链本身的天花板被掀了。TypeScript 7.0 已经把编译器用 Go 语言重写(代号 tsgo),2026 年 7 月正式 GA,编译速度快了约 10 倍。过去大项目里 CI 跑一次 tsc --noEmit 要一两分钟、VS Code 报错转半天圈的日子,正在被终结。对后端团队来说,这意味着类型检查可以从“卡点环节”变回“无感环节”,开更严格的检查不再有性能代价。
最后说两句
回头看,TypeScript 这东西不难学,难的是克制——克制住 as any 的冲动,克制住抄 tsconfig 的惯性,克制住“类型先不管、上线再说”的念头。它就像一个较真的会计,你账本记得越细,它越能帮你抓出窟窿;你随便涂改,它也只能干看着。
你现在的项目里,strict 开了吗?欢迎在评论区聊聊踩过的坑,说不定下一篇就写你的故事。
(参考资料:掘金:智能栈报、掘金:TypeScript 7.0 RC 解析、博客园:TypeScript 开发环境搭建)
