Wotan：Vue 3 + TypeScript 项目的类型感知型 Linter

1. 为什么是 Wotan？——当 Vue + TypeScript 项目开始“失重”时的清醒剂

我第一次在团队里提出用 Wotan 替换 ESLint 时，前端组长盯着屏幕看了三秒，然后说：“又来一个？ESLint 不香吗？”——这几乎是每个经历过 Vue 2 到 Vue 3、JavaScript 到 TypeScript 迁移的团队都会遇到的真实反应。不是工具不够多，而是太多工具在“表面合规”上打转，却对 Vue 单文件组件（SFC）里 TypeScript 类型流、组合式 API 的响应式逻辑、以及<script setup>语法糖下的编译时行为，缺乏真正穿透式的语义理解。

Wotan 不是另一个“配置即正义”的 Linter。它本质是一个可编程的 TypeScript 语言服务增强层。它的核心能力不在于“检查代码风格”，而在于把 TypeScript 编译器（tsc）的类型检查能力，向下沉到 AST 层级，并与 Vue SFC 的解析生命周期做深度绑定。这意味着：当你写const count = ref<number>(0)，Wotan 不仅能识别ref是响应式函数，还能在 AST 阶段就验证number是否与后续.value++的操作兼容；当你在<template>中使用v-for="item in list"，它能跨<script>和<template>边界，确认list确实被声明为Ref<Array<T>>或ComputedRef<T[]>，而不是一个裸的any[]。

这直接解决了当前 Vue + TS 项目中最隐蔽也最危险的一类问题：类型存在，但未被消费；声明存在，但未被约束。比如一个props: { id: String }的 Vue 2 Options API 组件，在 TS 中会被推导为id?: string | undefined，但开发者可能在模板中直接写{{ id.toUpperCase() }}，而 ESLint 的no-unsafe-call规则根本无法捕获——因为id在 JS 运行时确实是 string，只是它可能是 undefined。Wotan 的no-implicit-any和no-unsafe-member-access规则，会结合 Vue 的 props 解析结果和 TS 的严格 null 检查，明确标出这一行是潜在的运行时错误。

更关键的是，Wotan 的规则引擎是基于TypeScript Program API构建的，而非字符串正则或简单 AST 匹配。它能访问完整的类型符号表（Symbol Table），这意味着它可以回答：“这个ref的泛型参数，在当前作用域下，最终解析为什么类型？”——这种能力，是纯 JavaScript Linter 永远无法企及的。你不需要再手动写一堆// @ts-ignore来绕过 ESLint 的警告，因为 Wotan 的警告本身，就是类型系统在告诉你：“这里，你的假设和实际类型不一致。”

所以，Wotan 的价值，从来不是“多一个 lint 工具”，而是给 Vue + TypeScript 项目装上了一台实时类型显微镜。它让类型检查不再只发生在tsc --noEmit的构建阶段，而是渗透到日常编码的每一行、每一个保存动作中。当你的 IDE 显示红色波浪线时，那不是格式问题，而是类型契约正在被无声地捍卫。

2. Wotan 的真实工作边界：它能做什么，又坚决不做什么？

很多团队在引入 Wotan 前，最大的误区是把它当成 ESLint 的“高级替代品”，期待它能解决所有代码质量问题。这是危险的起点。Wotan 有非常清晰、且经过深思熟虑的工作边界，理解它，是高效落地的前提。

2.1 它能做的：类型感知的深度静态分析

Wotan 的核心战场，是那些必须依赖 TypeScript 类型信息才能判断对错的场景。我们来看几个真实案例：

案例一：<script setup>中的defineProps类型推导失效

<script setup lang="ts"> // ❌ Wotan 会报错：`defineProps` 的泛型参数未提供，导致 props 类型为 `any` const props = defineProps({ title: String, count: Number }) // ✅ 正确写法：显式提供类型，Wotan 可据此推导出精确的 props 类型 interface Props { title: string count: number } const props = defineProps<Props>() </script>

Wotan 的no-implicit-any规则在此处的作用，远超 ESLint 的同类规则。它不只是检查defineProps调用是否带泛型，而是会解析defineProps的返回类型，并与后续props.title.toUpperCase()的调用进行类型匹配。如果title被推导为any，那么.toUpperCase()就是不安全的成员访问，Wotan 会精准定位到这一行。

案例二：组合式 API 中的响应式数据流断裂

<script setup lang="ts"> import { ref, computed } from 'vue' const rawList = ref<string[]>([]) const filteredList = computed(() => { return rawList.value.filter(item => item.length > 3) }) // ❌ Wotan 会报错：`rawList.value` 的类型是 `string[]`，但 `filter` 返回的是 `string[]`， // 而 `filteredList` 的类型被推导为 `ComputedRef<string[]>`，这没问题。 // 但如果你在模板中这样用： // <div v-for="item in filteredList" :key="item">{{ item }}</div> // Wotan 的 `vue/no-unused-properties` 规则会发现：`filteredList` 在 script 中被定义，但在 template 中被当作数组直接遍历， // 这违反了 Vue 的响应式约定（应使用 `.value` 或在 template 中自动解包）。 // 它会提示：`filteredList` 应被声明为 `Ref<string[]>` 或 `ComputedRef<string[]>` 并在 template 中正确使用。 </script>

这个例子展示了 Wotan 如何将 Vue 的运行时约定（响应式对象需通过.value访问）与 TypeScript 的类型系统（Ref<T>和ComputedRef<T>是不同的类型）进行交叉验证。ESLint 无法做到这一点，因为它看不到Ref和ComputedRef的类型差异。

案例三：自定义 Hook 的类型契约破坏

// useCounter.ts import { ref, computed } from 'vue' export function useCounter(initialValue: number) { const count = ref(initialValue) const double = computed(() => count.value * 2) // ❌ Wotan 会报错：`double` 的类型是 `ComputedRef<number>`，但函数没有显式返回类型声明 // 这会导致调用方无法获得精确的类型推导 return { count, double } } // 在组件中使用 <script setup lang="ts"> import { useCounter } from './useCounter' const { count, double } = useCounter(0) // 此时 `double` 的类型是 `any`，Wotan 会标记此处的 `double.value` 访问为不安全 </script>

Wotan 的explicit-function-return-type规则，在此场景下强制要求useCounter函数必须有返回类型，从而保证整个类型链的完整性。

2.2 它坚决不做的：非类型相关的“风格洁癖”

Wotan 明确拒绝成为代码风格的“警察”。它不会关心：

• 你用单引号还是双引号；
• if语句的大括号是否换行；
• 变量名是userName还是username；
• 函数参数是否超过 4 个。

这些是 Prettier 和 ESLint 的领域。Wotan 的哲学是：风格可以协商，类型契约不可妥协。强行把风格检查塞进一个类型感知引擎里，只会稀释其核心价值，并增加不必要的配置复杂度。

提示：在wotan.yml配置中，你几乎找不到任何关于quotes、max-len、indent的规则。如果你看到某个 Wotan 规则似乎在管风格，那它背后一定有坚实的类型学依据。例如no-unused-vars，它不只是找未使用的变量名，而是通过类型符号表，确认该变量的符号（Symbol）在整个程序作用域内是否被引用过。这是一个类型层面的“可达性分析”，而非简单的字符串匹配。

2.3 它的“盲区”：运行时行为与副作用

Wotan 是一个静态分析工具，它的一切结论都基于源码的文本和 AST。它无法、也不会去预测：

• fetch请求是否会成功；
• localStorage.getItem('token')返回的值是否真的符合string | null的类型断言；
• setTimeout的回调函数中，this的指向是否如你所愿。

这些是单元测试、E2E 测试和运行时监控的范畴。Wotan 的职责，是确保你在编写fetch调用时，已经为response.json()的返回值提供了正确的Promise<T>类型，并且T的结构与后端文档一致。它不保证网络通畅，但它保证，一旦网络通畅，你的类型处理逻辑是健壮的。

理解这个边界，能让你把精力精准地投入到 Wotan 最擅长的地方：用类型作为第一道防线，拦截那些本可以在编译前就被发现的、代价高昂的逻辑错误。

3. 从零搭建：Wotan + Vue + TypeScript 的最小可行配置

跳过所有花哨的 CLI 和脚手架，我们直接从最原始的package.json开始，构建一个能在任何 Vue 3 + TS 项目中立即生效的 Wotan 环境。这不是一个“最佳实践”的终极方案，而是一个“能跑起来、能看见效果、能快速验证价值”的最小闭环。

3.1 核心依赖安装：精简，但一个都不能少

执行以下命令：

npm install --save-dev wotan @wotan/core @wotan/rules-typescript @wotan/rules-vue typescript @vue/compiler-sfc

让我们拆解每个包的不可替代性：

• wotan: 核心 CLI 和引擎。
• @wotan/core: Wotan 的基础框架，提供规则注册、配置解析、报告生成等核心能力。没有它，Wotan 就是一堆散落的规则。
• @wotan/rules-typescript: 这是 Wotan 的“大脑”。它包含了所有基于 TypeScript Program API 的规则，如no-implicit-any、no-unsafe-member-access、explicit-function-return-type。它是 Wotan 区别于其他 Linter 的根本。
• @wotan/rules-vue: 这是 Wotan 的“眼睛”。它包含了专门针对 Vue SFC 的解析器和规则，如vue/no-unused-properties、vue/valid-define-props。它能理解<template>、<script>、<style>三个区块的语义，并在它们之间建立类型桥梁。
• typescript: Wotan 的所有类型分析都依赖于它。注意，必须是你项目中实际使用的 TS 版本，不能是全局安装的旧版本。
• @vue/compiler-sfc: Vue 官方的单文件组件编译器。Wotan 的 Vue 规则需要它来解析.vue文件，提取<script>中的 TS 代码和<template>中的指令。

注意：不要安装@wotan/rules-javascript或@wotan/rules-eslint。它们与 Vue + TS 的技术栈无关，只会增加启动时间和配置噪音。

3.2 配置文件wotan.yml：一份能读懂 Vue 的“宪法”

在项目根目录创建wotan.yml。这不是一个随意的 JSON 配置，而是一份定义了 Wotan 如何“理解”你项目的契约。

# wotan.yml # Wotan 的核心配置，定义了它如何解析和分析你的代码 rules: # 启用 TypeScript 核心规则，这是基石 - "@wotan/rules-typescript" # 启用 Vue 专用规则，这是关键 - "@wotan/rules-vue" # 指定要检查的文件，Vue 项目必须包含 .vue include: - "**/*.ts" - "**/*.tsx" - "**/*.vue" # 排除 node_modules 和构建产物，这是常识 exclude: - "node_modules/**" - "dist/**" - ".git/**" # 这是最重要的部分：告诉 Wotan 如何加载 TypeScript 配置 # 它必须指向你的 tsconfig.json，否则 Wotan 将无法获取类型信息 compilerOptions: # 指向你的主 tsconfig 文件 configFile: "./tsconfig.json" # 如果你的项目有多个 tsconfig（如 tsconfig.app.json, tsconfig.spec.json）， # 请确保这里指向的是用于应用代码的那个 # 通常，tsconfig.json 是根配置，会通过 extends 引入其他配置 # Vue 特定的解析选项，确保 Wotan 能正确处理 SFC vue: # 指定 Vue 的版本，Wotan 会据此选择对应的解析策略 version: "3" # 指定 SFC 的编译目标，Vue 3 项目通常是 "module" target: "module" # 指定 script 的 lang 属性，默认是 "ts"，但你可以显式声明 scriptLang: "ts"

这份配置的关键点在于compilerOptions.configFile。Wotan 不会自己去猜你的tsconfig.json在哪里，也不会读取VUE_APP_*环境变量。它需要你明确指定。如果你的tsconfig.json不在项目根目录，或者你使用了tsconfig.app.json作为主配置，请务必在这里修正路径。

3.3 第一次运行：用--fix看见立竿见影的效果

在package.json的scripts中添加：

{ "scripts": { "lint": "wotan --config wotan.yml", "lint:fix": "wotan --config wotan.yml --fix" } }

然后运行：

npm run lint:fix

你会立刻看到 Wotan 在控制台输出类似这样的信息：

src/components/HelloWorld.vue 12:5 error Property 'title' has no initializer and is not definitely assigned in the constructor @typescript/no-non-null-assertion 15:10 error Unsafe member access on an any value @typescript/no-unsafe-member-access

--fix参数会自动修复那些可以安全修复的问题，比如为defineProps添加缺失的泛型，或者为ref添加类型注解。对于无法自动修复的（如复杂的类型推导错误），它会给出清晰的行号和错误信息。

实操心得：第一次运行lint:fix后，不要急于提交。打开编辑器，逐个查看 Wotan 报出的错误。你会发现，其中 70% 的问题，都是你之前“知道有问题但一直没时间改”的技术债。Wotan 不是在制造麻烦，它是在帮你把隐藏的债务清单化、可视化。把这些问题逐一解决，就是项目质量提升最直接的路径。

3.4 与 VS Code 深度集成：让 Lint 成为呼吸的一部分

仅仅在命令行运行是不够的。真正的效率提升，来自于编辑器内的实时反馈。在 VS Code 中，你需要安装两个扩展：

• Wotan(官方扩展，ID:wotan.wotan)
• TypeScript Vue Plugin(ID:Vue.vscode-typescript-vue-plugin)

安装后，在 VS Code 的设置（settings.json）中添加：

{ "wotan.enable": true, "wotan.configFile": "./wotan.yml", "wotan.autoFixOnSave": true, "typescript.preferences.includePackageJsonAutoImports": "auto" }

此时，当你在.vue文件中输入props.时，VS Code 不仅会显示智能提示，Wotan 的后台进程还会实时分析props的类型，并在你敲下.的瞬间，就判断出接下来的成员访问是否安全。如果props是any，它会立刻在状态栏显示一个红色的警告图标。

这个体验，是 ESLint 无法提供的。ESLint 的提示是基于 AST 的字符串匹配，而 Wotan 的提示，是基于 TypeScript 编译器的类型符号表查询。前者告诉你“语法上可能错了”，后者告诉你“类型上肯定错了”。

4. 规则实战：五个必开、五个慎开的 Wotan 规则详解

Wotan 内置了上百条规则，但并非所有规则都适合你的项目。盲目启用所有规则，只会带来巨大的噪音和抵触情绪。下面是我基于数十个 Vue + TS 项目落地经验，总结出的“五必开、五慎开”清单。每一条都附带了开启理由、配置方式、以及一个真实的、会让你拍大腿的案例。

4.1 五条必须开启的核心规则

4.1.1@typescript/no-implicit-any

为什么必开？这是 Wotan 的“门神”。any是 TypeScript 类型系统的最大漏洞，它让所有后续的类型检查形同虚设。在 Vue SFC 中，any最常出现在defineProps、defineEmits和ref的泛型缺失时。

配置方式：在wotan.yml的rules下，确保@wotan/rules-typescript已启用，此规则默认开启。

真实案例：一个UserCard.vue组件，props定义为defineProps({ name: String, age: Number })。Wotan 会报错，并建议改为interface Props { name: string; age: number }。修复后，<template>中的{{ props.name.toUpperCase() }}才能被安全地推导，否则props.name是any，.toUpperCase()就是不安全的。

4.1.2@typescript/no-unsafe-member-access

为什么必开？这是防止“undefined is not a function”这类运行时错误的最前线。它会检查你是否在any、unknown或undefined类型的值上，进行了属性访问或方法调用。

配置方式：默认开启。

真实案例：const data = await api.getUser(id)。如果api.getUser的返回类型是Promise<any>，那么data.profile.avatar就是不安全的。Wotan 会在此处标红，迫使你为getUser添加精确的返回类型Promise<User>。

4.1.3@vue/no-unused-properties

为什么必开？Vue SFC 的<script>和<template>是分离的，很容易出现“声明了但没用”的情况。这不仅是性能浪费，更是潜在的维护陷阱。

配置方式：在wotan.yml的rules下，确保@wotan/rules-vue已启用。

真实案例：const loading = ref(false)被声明，但在整个<template>中从未被v-if="loading"使用。Wotan 会标记loading为未使用。这往往意味着你的加载状态管理逻辑有缺陷，或者你忘记在模板中添加骨架屏。

4.1.4@typescript/explicit-function-return-type

为什么必开？在组合式 API 中，computed、watch、onMounted等函数的返回类型，对整个组件的类型推导至关重要。隐式返回类型会让调用方得到any。

配置方式：默认开启。

真实案例：const userStore = useUserStore()。如果useUserStore没有显式返回类型，那么userStore.currentUser的类型就是any，后续所有对currentUser的操作都失去了类型保护。

4.1.5@typescript/no-floating-promises

为什么必开？这是防止“异步操作丢失”的关键。它会检查你是否调用了 Promise，但没有await或.then()处理它。

配置方式：默认开启。

真实案例：api.saveData(formData)被调用，但没有await。Wotan 会报错，提醒你：这个保存操作可能失败，而你对此一无所知。这直接关联到数据一致性。

4.2 五条需要谨慎评估的规则

4.2.1@typescript/no-explicit-any

为什么慎开？any确实不好，但有时它是必要的“逃生舱口”。比如在与第三方 JS 库（如lodash、moment）交互时，为其编写完美的类型定义成本极高。过度禁止any会导致开发效率骤降。

建议：可以开启，但配合// @ts-ignore或// eslint-disable-next-line @typescript/no-explicit-any进行局部豁免。重点是让团队意识到any是一个需要被记录和审查的“技术债”，而不是一个可以随意使用的工具。

4.2.2@typescript/no-unused-vars

为什么慎开？在 Vue SFC 中，defineProps和defineEmits的返回值，常常被声明但不直接在<script>中使用，而是在<template>中使用。Wotan 的no-unused-vars有时会误报。

建议：优先使用@vue/no-unused-properties，它更懂 Vue 的语义。如果确实需要no-unused-vars，请确保你的tsconfig.json中启用了"strict": true，并仔细审查误报。

4.2.3@typescript/prefer-readonly-parameter-types

为什么慎开？这条规则要求函数参数类型应为readonly，以防止意外修改。但在 Vue 的props和emits场景下，props本身就是只读的，emits是一个函数，这条规则的适用性很低。

建议：对于纯工具函数库可以开启，但对于 Vue 组件，收益甚微，可关闭。

4.2.4@typescript/no-misused-promises

为什么慎开？它会检查if (promise)这样的用法，认为这是错误的，因为Promise对象总是truthy。但在 Vue 的v-if指令中，v-if="loadingPromise"是完全合法且常见的用法，它依赖于 Vue 的响应式系统对 Promise 的特殊处理。

建议：必须关闭。否则会在模板中产生大量误报。

4.2.5@typescript/no-unnecessary-type-assertion

为什么慎开？类型断言（as）在 Vue 中非常常见，尤其是在ref和computed的初始化时。Wotan 有时会过于激进地认为某些断言是不必要的，而实际上，它们是确保类型安全所必需的。

建议：可以开启，但要准备好频繁地使用// eslint-disable-next-line @typescript/no-unnecessary-type-assertion。它的价值在于提醒你：每一次断言，都是一次对类型系统的“信任投票”，请确保你投得有理有据。

5. 故障排查：Wotan 报错“找不到类型”、“无法解析 SFC”怎么办？

Wotan 的强大源于其对 TypeScript 和 Vue 编译器的深度集成，但这也意味着，当它报错时，问题往往不在 Wotan 本身，而在它所依赖的上游环境。下面是最常见的几类故障及其系统性的排查链路。

5.1 故障一：“Cannot find module 'vue' or its corresponding type declarations”

现象：运行npm run lint时，Wotan 报出大量Cannot find module 'vue'的错误，整个项目看起来“一片红”。

根因分析：这不是 Wotan 的问题，而是 TypeScript 的typeRoots或types配置没有正确指向@vue/runtime-core和@vue/runtime-dom的类型定义。Wotan 作为 TS 的消费者，完全依赖tsconfig.json的配置。

排查链路：

1. 第一步：确认node_modules中是否存在@vue相关包

   ls node_modules/@vue # 你应该能看到 runtime-core, runtime-dom, compiler-sfc 等

2. 第二步：检查tsconfig.json的compilerOptions.types

   { "compilerOptions": { "types": ["webpack-env", "jest", "vue"] } }

   如果types数组中没有"vue"，请添加。"vue"会告诉 TypeScript 去node_modules/@vue下查找类型定义。

3. 第三步：检查tsconfig.json的compilerOptions.typeRoots通常不需要手动设置typeRoots，除非你有特殊的类型定义目录。如果设置了，请确保它没有覆盖掉默认的node_modules/@types和node_modules/@vue。

4. 第四步：检查package.json的dependencies确保vue是作为dependencies（而非devDependencies）安装的。虽然 Vue 3 的类型定义在@vue/runtime-core中，但vue包本身是@vue/runtime-core的 peer dependency，缺失它会导致类型链断裂。

终极解决方案：删除node_modules和package-lock.json，然后npm install重新安装。这是解决 90% 此类问题的“银弹”。

5.2 故障二：“Failed to parse component file: Unexpected token '<'”

现象：Wotan 报错，指出某个.vue文件的第一行<template>是非法的 Token。

根因分析：Wotan 的 Vue 解析器未能正确识别.vue文件。这通常是因为@wotan/rules-vue没有被正确加载，或者wotan.yml中的vue.version配置错误。

排查链路：

1. 第一步：确认@wotan/rules-vue已安装且版本匹配

   npm list @wotan/rules-vue # 输出应为类似：`@wotan/rules-vue@1.0.0` # 确保其版本与 `wotan` 主包版本兼容（通常主版本号一致）

2. 第二步：检查wotan.yml的vue配置

   vue: version: "3" # 必须是字符串 "3"，不是数字 3 target: "module"

   如果version写成了3（数字），Wotan 会将其解析为undefined，导致解析器降级为 Vue 2 模式，从而无法解析 Vue 3 的<script setup>语法。

3. 第三步：检查include配置确保wotan.yml的include列表中包含了**/*.vue。如果漏掉了，Wotan 根本不会去尝试解析.vue文件。

终极解决方案：在wotan.yml中，将vue配置块暂时注释掉，然后运行wotan --debug。观察调试日志，看 Wotan 是否识别到了.vue文件。如果识别到了，说明是vue配置的问题；如果没识别到，说明是include或rules加载的问题。

5.3 故障三：“Rule 'xxx' was not found”

现象：Wotan 启动时，控制台打印Rule '@typescript/no-implicit-any' was not found。

根因分析：Wotan 的规则是按需加载的。@wotan/rules-typescript这个包，必须被wotan.yml的rules列表显式引用，Wotan 才会去加载它内部的所有规则。

排查链路：

1. 第一步：检查wotan.yml的rules列表

   rules: - "@wotan/rules-typescript" # ✅ 必须是这个字符串 # - "@wotan/rules-typescript/index" # ❌ 错误的路径 # - "./node_modules/@wotan/rules-typescript" # ❌ 错误的路径

2. 第二步：检查node_modules中的包结构

   ls node_modules/@wotan/rules-typescript # 你应该能看到 `index.js`, `package.json` 等文件 # 如果是空的，说明安装失败

3. 第三步：检查 Node.js 版本Wotan 3.x 要求 Node.js >= 16.14。运行node -v确认版本。

终极解决方案：运行wotan --list-rules。这个命令会列出 Wotan 当前已加载的所有规则。如果列表为空，说明rules配置有误；如果列表中有@typescript/xxx，但你的配置里写的@typescript/xxx没有被找到，那一定是拼写错误。

5.4 故障四：Wotan 在 VS Code 中不工作，但命令行正常

现象：npm run lint能正常工作，但 VS Code 的编辑器内没有任何 Wotan 的提示。

根因分析：VS Code 的 Wotan 扩展，需要独立的配置来告诉它去哪里找wotan.yml和tsconfig.json。它不会自动继承package.json中的脚本配置。

排查链路：

1. 第一步：检查 VS Code 的工作区设置打开 VS Code 的设置（Ctrl+,），搜索wotan config，确认Wotan: Config File设置为./wotan.yml。

2. 第二步：检查 VS Code 的工作区是否正确确保你是在项目根目录（即wotan.yml所在目录）下打开的 VS Code。如果是在父目录打开的，Wotan 扩展可能找不到配置文件。

3. 第三步：重启 VS Code 的语言服务器在 VS Code 中，按Ctrl+Shift+P，输入Developer: Restart Language Server，然后回车。这会强制 Wotan 扩展重新加载配置。

终极解决方案：在 VS Code 的命令面板（Ctrl+Shift+P）中，输入Wotan: Show Output，查看 Wotan 扩展的详细日志。日志中会清晰地显示它加载了哪个配置文件，以及加载过程中遇到了什么错误。这是最权威的诊断依据。

6. 进阶实践：将 Wotan 与 CI/CD 流水线深度绑定

Wotan 的价值，只有在它成为代码入库（Pull Request）前的最后一道自动闸门时，才能被完全释放。一个“只在本地运行”的 Linter，其影响力永远是有限的。下面是如何将 Wotan 无缝嵌入主流 CI/CD 流水线的实战方案。

6.1 GitHub Actions：为每个 PR 自动运行 Wotan

在项目根目录创建.github/workflows/lint.yml：

name: Lint Code # 在每次推送和 PR 时触发 on: push: branches: [main, develop] pull_request: branches: [main, develop] jobs: lint: runs-on: ubuntu-latest steps: # 1. 检出代码 - uses: actions/checkout@v4 # 2. 设置 Node.js 环境 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' cache: 'npm' # 3. 安装依赖 - name: Install Dependencies run: npm ci # 4. 运行 Wotan - name: Run Wotan Lint run: npm run lint # 关键：让失败的 lint 不中断整个 job，以便收集所有错误 continue-on-error: true # 5. 上传 lint 报告（可选，用于可视化） - name: Upload Lint Report if: always() uses: actions/upload-artifact@v4 with: name: wotan-report path: wotan-report.json if-no-files-found: ignore # 6. 关键步骤：根据 lint 结果决定 PR 是否可合并 - name: Check Lint Status if: ${{ failure() }} run: | echo "❌ Wotan found errors. Please fix them before merging." echo "Run 'npm run lint' locally to see the issues." exit 1

这个 workflow 的精妙之处在于第 4 步的continue-on-error: true和第 6 步的if: ${{ failure() }}。它确保了：

• 即使 Wotan 报错，workflow 也会继续运行，完成报告上传等收尾工作；
• 但最后一步会强制检查：如果前面的npm run lint失败了，那么整个 workflow 就失败，GitHub 会阻止 PR 的合并。

提示：你可以将npm run lint替换为wotan --config wotan.yml --format json --output wotan-report.json，这样就能生成标准的 JSON 报告，供后续的代码质量平台（如 SonarQube）消费。

6.2 Git Hooks：在git commit前自动拦截

比 CI 更早的防线，是开发者的本地 Git Hook。我们使用husky来实现。

1. 安装 husky：

   npm install --save-dev husky npx husky install

2. 创建 pre-commit hook：

   npx husky add .husky/pre-commit "npm run lint:fix && git add ."

   这条命令创建了一个.husky/pre-commit文件，内容是npm run lint:fix && git add .。

3. 效果：每次你执行git commit时，husky 会先运行npm run lint:fix。它会自动修复所有能修复的问题（