1. 为什么 TypeScript 项目还要再配一层 eslintTypeScript 自带类型检查很多人第一反应是「有 tsc 就够了还要 eslint 干嘛」。我一开始也这么想直到项目里出现any满天飞、console.log忘了删、useEffect依赖数组写错却编译通过的情况。tsc 管的是「类型对不对」eslint 管的是「写法好不好、有没有埋雷」两者是互补关系不是替代关系。这篇要解决的具体场景是在一个 TypeScript 项目里把 eslint 代码检查工具跑通同时把 eslint 相关的 AI 辅助能力比如让模型帮你解释一条报错、生成一段符合团队规范的修复代码统一走 TaoToken 的 Key/API 通道避免本地到处散落不同厂商的 Key。适合刚学 TypeScript、想一次性把工程化配置搭好的同学也适合团队里负责统一开发环境的人。读完你能拿到三样东西一份可直接复制的eslint.config.mjs骨架、一份 VSCodesettings.json配置、以及一套用 curl 验证「eslint 检查生效 TaoToken 通道可用」的具体命令。全程本地开发环境不需要动生产配置。先说清楚一个容易混的点eslint 从 v9 开始默认用扁平配置flat config也就是eslint.config.mjs老的.eslintrc.json虽然还能用但已经是过渡方案。网上很多教程还是.eslintrc写法你照着抄会发现npx eslint --init生成的文件名对不上这就是版本差异。下面统一按 v9 的扁平配置来写。2. TaoToken 前置把 Key 和 API 通道准备好eslint 本身是本地工具不联网也能跑。那 TaoToken 在这里扮演什么角色我的用法是把「AI 辅助写代码 / 解释报错 / 生成修复建议」这类需要调用大模型的能力统一收敛到一个 API 通道上。这样你在编辑器插件、命令行脚本、自己写的小工具里用的都是同一个 Key 和同一个 base URL换模型只改一个参数不用每个工具单独配一遍。TaoToken 在这里就是一个统一的模型调用入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址后面不加任何查询参数直接作为 base URL 用。你需要先拿到一个 API Key。进入控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面新建一个https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建后那串sk-开头的字符串只显示一次复制到本地环境变量里别直接写进会提交到 git 的文件。我习惯把它放进 shell 的 profile# ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api改完执行source ~/.zshrc然后用echo $TAOTOKEN_API_KEY确认能打印出来。这一步看着简单但后面所有脚本都依赖它先确认好能省很多排查时间。注意不要把 Key 写进eslint.config.mjs或settings.json里再提交。eslint 配置是团队共享文件Key 是个人凭证两者必须分开。需要给脚本传 Key 时从环境变量读。如果你后面要做长期的编码辅助、Agent 类任务可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用场景。只是偶尔问一句报错怎么修用按量计费的 Key 就够了。3. 可复制配置eslint.config.mjs 与 settings.json 骨架3.1 安装依赖先确认 Node 版本eslint v9 要求 Node 18.18 以上。然后装依赖注意typescript-eslint是 v8 系列和 eslint v9 配套npm init -y npm install -D eslint^9.18.0 eslint/js^9.18.0 globals^15.14.0 typescript^5.7.3 typescript-eslint^8.21.0装完package.json的devDependencies应该长这样{ devDependencies: { eslint/js: ^9.18.0, eslint: ^9.18.0, globals: ^15.14.0, typescript: ^5.7.3, typescript-eslint: ^8.21.0 } }3.2 eslint.config.mjs 骨架你可以用npx eslint --init交互式生成也可以直接复制下面这份。我建议先复制跑通再按需改// eslint.config.mjs import globals from globals; import pluginJs from eslint/js; import tseslint from typescript-eslint; /** type {import(eslint).Linter.Config[]} */ export default [ { files: [src/**/*.{js,mjs,cjs,ts}], }, { languageOptions: { globals: globals.browser, }, }, pluginJs.configs.recommended, ...tseslint.configs.recommended, { rules: { // 团队自定义规则放这里 no-console: warn, typescript-eslint/no-explicit-any: warn, typescript-eslint/no-unused-vars: [ error, { argsIgnorePattern: ^_ }, ], }, }, ];几个关键点解释一下。files决定检查哪些文件这里限定src下的 js/ts。globals.browser让window、document这类全局变量不被误报为未定义。pluginJs.configs.recommended是 eslint 官方推荐规则tseslint.configs.recommended是 TypeScript 专属规则集。最后一段rules是你覆盖或新增的地方no-console设成warn而不是error是因为开发阶段调试打印很常见设成 error 会打断流程。3.3 VSCode settings.json 骨架编辑器里要装 ESLint 插件作者是 Microsoft版本 3.x。然后在项目根目录建.vscode/settings.json{ eslint.useFlatConfig: true, eslint.validate: [ javascript, javascriptreact, typescript, typescriptreact ], editor.codeActionsOnSave: { source.fixAll.eslint: explicit }, eslint.workingDirectories: [{ mode: auto }] }eslint.useFlatConfig必须为 true否则插件还在找老的.eslintrc你会看到「配置没生效」的假象。editor.codeActionsOnSave让保存时自动修复能修的问题explicit是 v3 插件的新写法老教程里的true已经废弃。3.4 把 AI 辅助脚本接到 TaoToken下面这个脚本演示怎么用同一个 Key 调模型帮你解释一条 eslint 报错。存成scripts/explain-lint.mjs// scripts/explain-lint.mjs const apiKey process.env.TAOTOKEN_API_KEY; const baseUrl process.env.TAOTOKEN_BASE_URL || https://taotoken.net/api; if (!apiKey) { console.error(缺少 TAOTOKEN_API_KEY 环境变量); process.exit(1); } const lintMessage process.argv.slice(2).join( ) || Unexpected any; const res await fetch(${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey}, }, body: JSON.stringify({ model: gpt-4o-mini, messages: [ { role: system, content: 你是 TypeScript 代码审查助手用中文简短解释报错并给出修复示例。, }, { role: user, content: 这条 eslint 报错是什么意思${lintMessage} }, ], }), }); const data await res.json(); console.log(data.choices?.[0]?.message?.content ?? JSON.stringify(data));运行方式node scripts/explain-lint.mjs typescript-eslint/no-explicit-any模型名按你账号里可用的填这里只是示例。核心是baseUrl和Authorization头换任何兼容 OpenAI 格式的客户端都是这两处。4. 验证请求确认 eslint 生效且通道可用4.1 先验证 eslint 本身建一个故意写错的文件src/bad.ts// src/bad.ts const data: any { name: test }; console.log(data); function unused(a: number) { return a; }跑检查npx eslint src/bad.ts预期输出类似/path/src/bad.ts 2:12 warning Unexpected any. Specify a different type typescript-eslint/no-explicit-any 3:1 warning Unexpected console statement no-console 4:10 error unused is defined but never used typescript-eslint/no-unused-vars ✖ 3 problems (1 error, 2 warnings)看到这三条就说明规则生效了。如果一条都不报先看第 5 节的排查。4.2 再验证 TaoToken 通道用 curl 直接打一次确认 Key 和 base URL 没问题curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话说明 eslint 和 tsc 的区别}] }返回里能看到choices[0].message.content就是通了。如果返回 401是 Key 问题返回 404检查 base URL 有没有多写或少写/v1。想直接在网页里试模型可以用模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 不用写代码就能验证。4.3 自动修复验证eslint 能自动修一部分问题试试npx eslint src/bad.ts --fixno-unused-vars这类通常修不了需要你手动删但格式类问题会被改掉。修完再跑一次npx eslint src/bad.ts看剩余报错是否减少。这一步能帮你确认--fix链路是通的。5. 本篇常见错排查5.1 eslint 完全没反应最常见的原因是 VSCode 插件和项目本地 eslint 版本对不上。插件默认可能用自己内置的 eslint而不是你node_modules里的。在settings.json里加一句强制用本地版本{ eslint.nodePath: ./node_modules }另外确认eslint.useFlatConfig是 true。如果项目里同时存在.eslintrc.json和eslint.config.mjsv9 会优先扁平配置但插件可能犯迷糊把老的删掉最省事。5.2 报「Parsing error: Cannot read file tsconfig.json」这是typescript-eslint的类型感知规则需要 tsconfig 路径。如果你用了recommendedTypeChecked这类配置要在languageOptions里指定{ languageOptions: { parserOptions: { project: ./tsconfig.json, tsconfigRootDir: import.meta.dirname, }, }, }注意import.meta.dirname在 Node 20.11 才可用低版本用path.dirname(fileURLToPath(import.meta.url))替代。如果只是用recommended不带 TypeChecked不需要这段。5.3 全局 eslint 和本地 eslint 打架如果你之前npm install -g eslint装过全局的命令行里eslint可能指向全局版本和项目里的 v9 行为不一致。用npx eslint强制走本地或者yarn global upgrade eslint把全局也升上去。我踩过的坑就是全局还是 v8跑扁平配置直接报语法错排查了半天才发现是版本问题。5.4 TaoToken 返回 401 或超时先echo $TAOTOKEN_API_KEY确认变量在当前终端可见。如果你在 VSCode 里跑脚本注意 VSCode 可能没继承你刚改的 shell 环境重启一下编辑器。超时的话检查网络能否访问https://taotoken.net/api公司网络有时会拦外部 API这种情况找运维加白名单别自己乱配代理。5.5 保存时不自动修复确认editor.codeActionsOnSave写的是explicit而不是true。v3 插件改了 API老写法静默失效。另外eslint.validate里要包含typescript只写javascript的话.ts文件不会被处理。6. 把这条链路固定下来配置跑通之后建议做两件收尾的事。第一把npx eslint src --max-warnings 0加进package.json的 scriptsCI 里也跑同一条命令保证本地和流水线标准一致{ scripts: { lint: eslint src --max-warnings 0, lint:fix: eslint src --fix } }第二把 AI 辅助脚本的调用也收敛到同一个环境变量体系里别在某个脚本里硬编码 Key。这样你换机器、换项目只要TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL在所有工具都能直接用。需要看接口细节时翻接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有完整的请求格式和参数说明。最后留一个实用习惯每次升级 eslint 或typescript-eslint大版本后先跑一遍npx eslint src看有没有规则行为变化再提交。扁平配置时代规则合并逻辑和老版本不同升级后报错数量突变是正常的别慌逐条看就行。