1. 从一次tsc报错说起can only be default-imported到底在说什么如果你在 TypeScript 项目里写过import request from request或者import express from express大概率见过这条红字Module /xxx/node_modules/types/request/index.d.ts uses export and cannot be used with export default. This module can only be default-imported using the esModuleInterop flag.第一次看到它很多人会本能地去改 import 写法比如换成import * as request from request结果又冒出This expression is not callable。来回折腾半小时代码没跑起来心态先崩了。这条报错的本质是TypeScript 的模块系统和CommonJS 的模块系统在“默认导出”这件事上理解不一致。CommonJS 里module.exports fn这种写法在 Node 运行时是“整个模块就是一个函数”而 ES Module 规范里export default fn才是默认导出。TypeScript 为了兼容两套体系提供了一个编译开关esModuleInterop打开它之后编译器会自动帮你把export 的 CommonJS 模块“包装”成带default属性的形式于是import request from request就能正常工作了。所以这条报错不是你的代码写错了而是tsconfig 的编译选项没打开对应的互操作能力。它常出现在三类场景老项目从ts-node迁到tsc构建、monorepo 里子包的 tsconfig 没继承根配置、以及用tsx/esbuild跑得好好的代码一进tsc --noEmit就报错。这三种情况的共同点都是“本地 tsconfig.json 与构建链路配置不一致”。这篇内容就围绕这个报错把 tsconfig 关键字段、可复制的配置片段、验证命令和常见坑一次讲清楚。适合正在用 TypeScript 写 Node 服务、CLI 工具或者维护老项目的同学。核心检索词就是typescript esModuleInterop default-imported你按下面的步骤改完tsc --noEmit应该能干净通过。先说结论九成情况只需要在 tsconfig.json 的compilerOptions里加上esModuleInterop: true再配合allowSyntheticDefaultImports: true。但为什么加了还不生效、加了之后别的报错又冒出来才是真正值得展开的部分。下面从环境准备讲到排障每一步都能直接复制。2. 前置准备确认你的 TypeScript 版本与 tsconfig 生效路径动手改配置之前先确认两件事TypeScript 版本以及当前项目真正生效的 tsconfig 文件是哪一个。很多人改了根目录的 tsconfig.json 却没生效就是因为实际编译用的是子目录或extends链上的另一个文件。先看版本。esModuleInterop从 TypeScript 2.7 就引入了现在基本不用担心版本太低但不同大版本对export 的处理细节有差异建议 4.x 以上npx tsc --version # 输出示例Version 5.4.5再看当前目录下 TypeScript 实际读取的配置。tsc --showConfig会把extends合并后的最终配置打印出来这是排查“改了没生效”最快的手段npx tsc --showConfig输出里重点找esModuleInterop、allowSyntheticDefaultImports、module、moduleResolution这几个字段。如果esModuleInterop是false或者压根没出现那报错就说得通了。接着确认 tsconfig 的继承关系。一个典型的 monorepo 结构长这样repo/ ├── tsconfig.base.json # 根配置放公共 compilerOptions ├── packages/ │ ├── api/ │ │ └── tsconfig.json # extends ../../tsconfig.base.json │ └── cli/ │ └── tsconfig.json子包的 tsconfig.json 通常是这样{ extends: ../../tsconfig.base.json, compilerOptions: { outDir: dist, rootDir: src }, include: [src] }问题就出在这里如果esModuleInterop只写在子包里另一个子包没写或者根配置里写的是false被子包继承那不同包的行为就不一致。统一在tsconfig.base.json里打开互操作开关是最省心的做法。还有一个容易忽略的点编辑器VS Code用的 TypeScript 版本可能和项目node_modules里的不一致。VS Code 右下角可以切换 “Use Workspace Version”确保它读的是项目里的typescript。否则会出现“命令行tsc通过了编辑器还飘红”的割裂现象。如果你打算把模型调用、代码补全这类能力接进项目做联调可以先把 API Key 准备好。TaoToken 的 API Key 在控制台创建地址是 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 。这一步和修 tsconfig 没有强依赖但后面验证模块导入是否正常时用真实的 SDK 调用会比空跑更有说服力。3. 可复制配置tsconfig.json 关键字段与三种模块场景这一节是全文的核心直接给可复制的配置。先给一份“通用推荐版”再按module取值分场景说明。通用推荐版tsconfig.base.json{ compilerOptions: { target: ES2020, module: CommonJS, moduleResolution: Node, esModuleInterop: true, allowSyntheticDefaultImports: true, forceConsistentCasingInFileNames: true, strict: true, skipLibCheck: true, resolveJsonModule: true, declaration: true, sourceMap: true, outDir: dist, rootDir: src }, include: [src/**/*.ts], exclude: [node_modules, dist] }几个字段的作用要讲清楚不然你只是抄了个配置下次换个场景又懵esModuleInterop是总开关。打开后TypeScript 会为 CommonJS 模块生成辅助函数__importDefault把export 的模块包装成{ default: module }于是import request from request编译后变成const request_1 __importDefault(require(request))运行时取request_1.default就能拿到函数本身。allowSyntheticDefaultImports只影响类型检查不影响编译产物。它允许你从没有default导出的模块里写默认导入而不报类型错。通常和esModuleInterop一起开但严格来说开了esModuleInterop后这个选项会自动为true显式写出来只是让意图更清晰。module和moduleResolution决定模块解析策略。Node 项目用CommonJSNode如果产物要跑在浏览器打包器里用ESNextBundlerTS 5.0或Node。下面按三种常见场景给配置。场景一Node 服务编译成 CommonJS 产物。这是最典型的场景request、express、mongoose这类老库都属于此类。用上面的通用推荐版即可module保持CommonJS。场景二用 tsx / ts-node 直接跑 TS不产出 JS。这类工具内部用 esbuild 或 swc 转译它们默认就做了互操作所以运行时可能不报错但tsc --noEmit会报。配置上依然要开esModuleInterop同时建议加一个tsconfig专门给类型检查用{ compilerOptions: { module: ESNext, moduleResolution: Bundler, esModuleInterop: true, allowSyntheticDefaultImports: true, noEmit: true, strict: true, skipLibCheck: true } }场景三ESM 原生项目package.json 里type: module。这种项目里import request from request在 Node 运行时本身就会失败因为 CommonJS 模块在 ESM 下没有默认导出。正确做法是用createRequire或者换用支持 ESM 的库。tsconfig 层面{ compilerOptions: { module: NodeNext, moduleResolution: NodeNext, esModuleInterop: true, allowSyntheticDefaultImports: true, target: ES2022 } }注意NodeNext下导入 CommonJS 模块时 TypeScript 会强制你写import request from request并配合esModuleInterop但运行时 Node 会做一层default包装行为是自洽的。如果你在项目里同时要接模型对话做联调TaoToken 的模型对话入口在 https://taotoken.net/model-chat 可以先用它验证 SDK 的导入和调用是否正常再回到本地跑tsc。配置改完别忘了检查package.json里的type字段和构建脚本是否一致。见过太多“tsconfig 开了esModuleInterop但ts-node用的是另一份配置”的案例根因就是构建链路各读各的配置。4. 验证请求tsc --noEmit与项目启动命令的完整跑通流程配置写完必须验证。验证分两层类型检查层和运行时层。两层都过才算真的修好。先写一个最小复现文件src/index.tsimport request from request; request(https://taotoken.net/api, (err, res, body) { if (err) { console.error(request failed:, err.message); return; } console.log(status:, res res.statusCode); });然后跑类型检查npx tsc --noEmit如果配置正确这条命令应该没有任何输出退出码为 0。你可以用echo $?确认npx tsc --noEmit echo type check passed如果还有报错先别急着改代码用--showConfig确认esModuleInterop真的是truenpx tsc --showConfig | grep -i esModuleInterop输出应该是esModuleInterop: true。如果显示false或没有说明你改的 tsconfig 不是当前生效的那份回到第 2 节检查extends链。类型检查过了再验证运行时。编译并执行npx tsc node dist/index.js预期输出类似status: 200这一步能跑通说明__importDefault辅助函数正确生成了。你可以打开dist/index.js看一眼编译产物会看到类似这样的代码const request_1 __importDefault(require(request)); request_1.default(https://taotoken.net/api, ...);这就是esModuleInterop在背后做的事。如果你的项目用ts-node或tsx启动命令分别是npx ts-node src/index.ts # 或 npx tsx src/index.ts注意ts-node默认读tsconfig.json但如果你用了--project指定了别的文件要确保那份文件也开了esModuleInterop。tsx基于 esbuild运行时通常不报错但类型检查仍要靠tsc --noEmit。再补一个真实一点的验证用 TaoToken 的 API 做一次模型调用确认 SDK 导入和网络请求都正常。假设你用openai这个包它也是 CommonJS 导出代码import OpenAI from openai; const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: https://taotoken.net/api, }); async function main() { const res await client.chat.completions.create({ model: gpt-4o-mini, messages: [{ role: user, content: ping }], }); console.log(res.choices[0].message.content); } main();跑之前设置环境变量export TAOTOKEN_API_KEY你的Key npx tsx src/chat.ts如果这里报reading choices之类的错多半是响应结构没对上属于运行时问题不是esModuleInterop的锅排查方向见下一节。API Key 在 https://taotoken.net/api-keys 创建模型 ID 和 Base URL 以接入文档 https://taotoken.net/doc 为准。验证通过后建议把tsc --noEmit加进 CI 或pre-commit防止以后有人改配置把互操作开关关掉。一个简单的package.json脚本{ scripts: { typecheck: tsc --noEmit, build: tsc, start: node dist/index.js } }5. 常见错排查401、local proxy failed、reading choices 与 OAuth 报错对照修esModuleInterop的过程中往往会牵出别的报错。这一节把高频错误和对应根因列出来方便你对号入座。报错一error TS1259: Module can only be default-imported using the esModuleInterop flag。这就是本篇主角。根因是esModuleInterop没开或没生效。解决确认生效的 tsconfig 里esModuleInterop: true用tsc --showConfig验证。如果开了还报检查是不是有多个 tsconfig 冲突或者编辑器用了内置 TS 版本。报错二401 Unauthorized或Incorrect API key provided。这是运行时鉴权失败和 tsconfig 无关。检查三点环境变量是否真的注入echo $TAOTOKEN_API_KEY、Key 是否有多余空格或换行、Base URL 是否写成了https://taotoken.net/api注意结尾不要多加/v1具体以文档为准。Key 在 https://taotoken.net/api-keys 重新生成一个再试。报错三local proxy failed或连接超时。这类错误通常出现在请求根本没发出去的时候。先确认本机网络能访问目标域名再检查代码里有没有硬编码的代理配置。如果你在 CI 环境跑注意 CI 的网络策略可能和本地不同。排查顺序curl -I https://taotoken.net/api看连通性再看 SDK 初始化参数。报错四Cannot read properties of undefined (reading choices)。这个错说明请求发出去了但响应结构和你预期的不一样。常见原因模型 ID 写错导致返回了错误对象、流式和非流式响应混用、或者 SDK 版本和 API 不匹配。打印完整响应体定位const res await client.chat.completions.create({ /* ... */ }); console.log(JSON.stringify(res, null, 2));如果返回体里是{ error: {...} }那就是参数或鉴权问题不是choices缺失。报错五OAuth 相关报错比如OAuth token exchange failed或invalid_grant。这类错误出现在用 OAuth 方式接入的场景和esModuleInterop完全无关。检查 client id / secret 是否配对、回调地址是否在白名单、token 是否过期。如果你用的是 Claude Code 这类工具配置项通常在~/.claude/settings.json或项目级配置里Base URL、Key、Model ID 三件套要写全{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的Key, ANTHROPIC_MODEL: claude-3-5-sonnet-latest } }报错六Cannot find module request or its corresponding type declarations。这是类型声明缺失不是互操作问题。装类型包npm i -D types/request如果库本身没有类型声明在src/types/shims.d.ts里加declare module some-cjs-lib;排查这类问题的通用思路先分清是编译期错误还是运行期错误。tsc --noEmit报的错是编译期改 tsconfig 或类型声明node dist/index.js报的错是运行期查网络、鉴权、参数。两者混在一起看很容易改错方向。6. 把配置固化下来长期编码与 Agent 场景的接入建议配置改对一次不难难的是让它在团队里、在多个项目里、在长时间迭代里一直对。这一节讲怎么固化。第一把esModuleInterop写进团队的基础 tsconfig用extends分发。不要每个子包各写一份否则迟早出现“这个包能跑那个包报错”。基础配置放仓库根目录子包只写outDir、rootDir、include这类差异化字段。第二把tsc --noEmit加进 CI。一个最小 GitHub Actions 片段name: typecheck on: [push, pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx tsc --noEmit这样任何人改配置导致互操作开关失效PR 阶段就会被拦下来。第三如果你在用 Claude Code、Cline 这类编码 Agent 做长期开发建议把项目约定写进CLAUDE.md或.clinerules明确“所有 tsconfig 必须继承根配置禁止单独关闭 esModuleInterop”。Agent 读得到这些约定生成的代码和配置就不容易跑偏。需要长期跑 Agent 任务的话Coding Plan 入口在 https://taotoken.net/coding-plan 配合项目级配置使用。第四模型 ID 和 Base URL 这类会变的信息抽到环境变量或单独的配置文件不要散落在代码里。一个config.tsexport const config { baseURL: process.env.TAOTOKEN_BASE_URL ?? https://taotoken.net/api, apiKey: process.env.TAOTOKEN_API_KEY ?? , model: process.env.TAOTOKEN_MODEL ?? gpt-4o-mini, };这样换模型、换环境只改一处。最后说个我踩过的坑有次在 monorepo 里根 tsconfig 开了esModuleInterop但某个子包的tsconfig.json里写了esModuleInterop: false想“保持严格”结果那个包单独构建时全挂。extends是覆盖语义子包显式写的值会盖掉根配置。所以要么别写要么写对。用tsc --showConfig在子包目录下跑一遍就能看到最终生效值。把上面这些做完can only be default-imported这类报错基本不会再回来找你。核心就一句话让所有构建链路读同一份开了esModuleInterop的配置并用tsc --noEmit守住它。