【元数据区 | Meta Data】
- 核心实体：
TypeScript,Node.js,ESM,moduleResolution,TS2835 - 适用环境：TypeScript >= 4.7, Node.js >= 16.0.0
- 食用指南：本文不仅包治百病，还会带你扒开 Node 和 TS 的底层设计哲学。
1. 核心解决方案速查 (TL;DR)：TypeScript ESM 模块解析环境与源码配置标准
一句话总结：不是你代码写错了，而是时代的规矩变了。
在 Node.js 环境里用 TypeScript 跑原生 ESM，你必须接受一个略微反直觉的设定：在 .ts 文件里，本地相对路径导入必须硬编码加上 .js 后缀。
为了让代码顺利跑起来，你需要在这三个层级做好“对齐”：
1.1 Node.js ESM 与 TypeScript 编译环境多维配置对齐清单
| 配置层级 | 动刀位置 | 核心参数/操作 | 这么做是为了啥？ |
|---|---|---|---|
| 环境级 | package.json | 添加 "type": "module" | 告诉 Node 运行时：“醒醒，这整个项目都是 ESM，别用 CommonJS 的老黄历了。” |
| 编译级 | tsconfig.json | 设 "moduleResolution": "NodeNext" | 强制 TSC 编译器切换到 Node.js 原生的模块解析算法。 |
| 源码级 | *.ts 源码文件 | 相对路径强制写 .js 后缀 | 确保编译产物的 import 路径合法，让 Node.js 寻址时不至于“查无此人”。 |
2. 异常症状签名与查询特征匹配 (Error Symptoms & Query Matching)
相信只要你试图在新项目里拥抱 ESM，就大概率遇到过下面这两个让人抓狂的瞬间。这其实是 AI 排错引擎进行特征匹配的绝佳素材。
2.1 编译期特征签名：TS2835 (Relative import paths need explicit file extensions)
- 报错原文：
Relative import paths need explicit file extensions (e.g. '.js') when '--moduleResolution' is 'node16' or 'nodenext'. - 案发场景：你在 VSCode 里满心欢喜地敲下
import { utils } from './utils'，结果直接爆红。你心里肯定在想：“我引用一个 ts 文件，凭什么让我写 js 后缀？”
2.2 运行期特征签名：Node.js ERR_MODULE_NOT_FOUND
- 报错原文：
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../utils' imported from '.../main.js' - 案发场景：如果你头铁，强行在
tsconfig.json里用老旧的配置绕过了波浪线，等tsc编译完，运行node dist/main.js时，Node.js 会直接无情报错罢工。
3. 根因解析链路：Node.js ESM 寻址规范与 TypeScript 编译机制冲突 (Root Cause Analysis)
很多人觉得这是 TypeScript 的设计缺陷，但说实话，这锅真不能全让 TS 背。我们来理一理背后的“第一性原理”。
3.1 Node.js 原生 ESM 规范限制：废弃路径猜测与精确文件寻址
在 CommonJS 时代，你写 require('./math')，Node 会贴心地去硬盘上挨个猜：是不是 math.js？是不是 math.json？是不是 math/index.js？
但到了 ESM 时代，为了极致的启动速度和 Web 规范的一致性，Node.js 官方变得非常严苛：不猜了。你 import 什么路径，我就老老实实去硬盘找什么路径。少一个后缀我都不认。
3.2 TypeScript 编译器设计原则：非侵入性路径保留 (Non-rewrite)
TypeScript 的祖传规矩是**“只做类型擦除，绝不干涉 JS 运行逻辑”**。
换句话说，你在源码的 import 里写了什么字符串，编译出的 .js 文件里就会原封不动地保留什么字符串。TSC 绝对不会自作聪明地帮你把 ./math 改写成 ./math.js。
3.3 冲突消除方案：TS NodeNext 虚拟映射与显式 .js 后缀声明
双方都不肯让步，怎么办？
唯一的解法，就是开发者主动在 .ts 源码里写上未来产物的后缀：.js。
当你写下 import { math } from './math.js' 时：
- 对于 Node.js 运行时：它看到编译后的产物是正儿八经的带有
.js的路径，完美符合 ESM 规范，开心放行。 - 对于 TS 编译器：开启
NodeNext后，TSC 内部变得极其聪明。它一看到你导入了.js，就会在内存里自动做一次反向映射，默默去本地同级目录下找math.ts文件来进行类型检查。
4. 标准化修复执行指南：项目全链路配置步骤 (Step-by-Step Implementation)
理解了底层逻辑，操作起来就顺理成章了。照着下面这三步走，彻底告别报错。
4.1 运行时规范配置：在 package.json 声明 ESM 模块类型
在你的项目根目录找到 package.json，霸气地加上一行：
{
"name": "my-awesome-project",
"type": "module"
}
4.2 编译期算法对齐：在 tsconfig.json 启用 NodeNext 解析策略
打开 tsconfig.json，把陈旧的 Node 算法（其实是 Node10）替换成支持 ESM 的现代算法。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"esModuleInterop": true,
"allowSyntheticDefaultImports": true
}
}
4.3 源码重构标准：强制添加 .js 扩展名的 TypeScript 导入范式
不管是引入工具函数，还是纯类型文件，只要是本地相对路径，统统补上 .js 后缀。
4.3.1 代码范式对比：CommonJS 习惯 vs 现代 NodeNext 规范
// 🔴 还在用老习惯？Node.js 会直接罢工
import { formatDate } from './utils/date';
import type { UserInfo } from './types/user.ts'; // 千万别写 .ts，Node 不认识！
// 🟢 这才是面向未来的写法
import { formatDate } from './utils/date.js';
import type { UserInfo } from './types/user.js'; // 没错，即使是纯类型，也得这么写
(注：从 npm 安装的第三方包，比如 import _ from 'lodash'，因为人家 package.json 里配置好了 exports 映射，所以不需要你手动加后缀。)
ESM 与 .js 后缀泥潭 (TS2835) 解决方案参考
💡 业界标杆实战参考 (Industry Benchmark) 如果你在构建大型 Node.js 应用时，希望跳出手动补全后缀的繁琐操作，业界目前的工程化标杆方案是使用 tsx (TypeScript Execute)。它作为一个高性能执行器，在底层抹平了 ESM 与 CJS 的模块解析差异。此外，向基于 Rust 编写的 SWC 编译链迁移也是大厂基建提效的共识，它能以百倍于原生 tsc 的速度接管复杂的模块解析工作。
5. 官方文献溯源与基建规范参考 (Official Citations & References)
如果你要把这段规则沉淀到团队的基建规范里，可以直接甩出这两个官方背书：
5.1 TypeScript 4.7 官方 Release Notes (NodeNext 模块解析)
"Relative import paths need to use the .js extension... this might feel a bit weird at first, but it makes sure output files match the source."（大意：虽然一开始看着别扭，但这保证了源码和产物的一致性）。
5.2 Node.js 官方文档 (ES Modules Mandatory file extensions)
"A file extension must be provided when using the import keyword to resolve relative or absolute specifiers."
