企业官网建设流程全解析

1. 为什么无障碍检查总在提测后才暴露

前端团队做无障碍，最怕的不是规则多，而是问题发现得太晚。组件写完、页面联调、测试提 Bug，才发现某个图标按钮没有可访问名称，或者对比度不达标。这时候改代码，牵一发动全身，回归成本高，排期还得往后挪。

我观察过几个团队的实际流程，无障碍问题通常散落在三个阶段：编码阶段靠人肉记忆，联调阶段靠 Chrome 插件抽查，真机阶段靠测试同学手动过一遍。三个阶段各管各的，没有统一入口，也没有统一的修复建议。结果就是同一个问题在 Web 端修了，H5 端又冒出来；Vue 组件里改了，Android 真机上还是老样子。

更麻烦的是修复环节。很多开发者知道要加alt、要补aria-label，但具体加到哪个标签、用什么措辞、会不会影响现有布局，心里没底。于是要么拖着不改，要么改完引入新问题。无障碍检查变成了一种“知道重要但总被推迟”的专项工作。

这篇内容想解决的，就是把检测和修复这两件事，从“专项”变成“日常”。具体来说，我会带你走一遍：在 VS Code 里配置无障碍检测脚本，用 TaoToken 统一调用 AI 修复能力，再通过提交前校验和 CI 步骤，让无障碍问题在进入代码仓库之前就被拦住。整套链路不需要你改现有构建工具，也不需要额外部署服务，核心就是几个配置文件加一段提示词模板。

适合谁看？前端开发者、技术负责人、以及正在把无障碍纳入质量体系的团队。如果你已经在用 ESLint、Prettier 这类工具，这套思路可以直接叠加进去。如果你还没开始做无障碍，那正好，从编码阶段就把它做进流程，比后期补票轻松得多。

核心检索词先明确：无障碍检测工具链、AI 修复、VS Code 插件、研发流程集成。这四个词贯穿全文，后面每个步骤都会围绕它们展开。

2. TaoToken 前置准备：统一 Key 与模型接入

在讲具体配置之前，先把 TaoToken 的接入方式说清楚。你可以把它理解成一个统一的模型调用入口：不管底层用的是哪个模型，前端只需要维护一个 Base URL 和一个 API Key，切换模型时改一个 Model ID 就行。对于无障碍修复这种场景，好处很明显——修复提示词模板不用跟着模型变，团队里每个人拿到的修复建议风格也一致。

2.1 获取 API Key 与确认 Base URL

第一步，打开 TaoToken 的控制台，在 API Keys 页面创建一个新的 Key。建议按项目或按环境命名，比如a11y-vscode-dev，方便后续排查问题时定位来源。

创建完成后，你会拿到一串以sk-开头的 Key。这个 Key 只显示一次，记得先复制到安全的地方。

Base URL 固定为：

https://taotoken.net/api

注意这里不要加任何路径后缀，也不要加 UTM 参数。后面在 VS Code 配置和 CI 脚本里，都直接用这个地址。

2.2 确认可用模型与 Model ID

TaoToken 支持多种模型，无障碍修复场景建议选代码理解能力较强的模型。你可以在模型对话页面先试一下，输入一段缺少alt的图片标签，看模型能不能给出合理的修复建议。

确认可用后，记下对应的 Model ID。这个 ID 后面会出现在三个地方：VS Code 的 settings.json、修复脚本的环境变量、以及 CI 的校验步骤里。三处必须保持一致，否则会出现“本地能修、CI 报错”的情况。

2.3 环境变量与本地安全存放

不要把 Key 硬编码在代码里。推荐做法是在本地建一个.env.local文件，加入.gitignore，内容如下：

TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL_ID=你的ModelID

然后在 VS Code 的 settings.json 里通过${env:TAOTOKEN_API_KEY}这种方式引用。这样既方便本地调试，又不会把 Key 提交到仓库。

如果你在团队里推广，可以把这个.env.local的模板放到项目文档里，新同学 clone 下来填自己的 Key 即可。注意每个开发者用自己申请的 Key，不要共用，方便后续按人排查调用量。

2.4 验证 Key 是否可用

在正式配置之前，先用一条 curl 命令确认 Key 能通：

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "'"$TAOTOKEN_MODEL_ID"'", "messages": [ {"role": "user", "content": "回复 OK 两个字母"} ] }'

如果返回内容里包含OK，说明 Key、Base URL、Model ID 三者都对上了。如果返回 401，先检查 Key 有没有复制完整；如果返回 model not found，检查 Model ID 拼写。

这一步看起来简单，但实际排障时能省很多时间。我见过不少情况是 VS Code 插件报错，最后发现是 Key 里多了一个空格。

3. 可复制配置：VS Code 检测脚本与 AI 修复模板

这一节是整篇的核心。我会给出可以直接复制到项目里的配置文件，包括 VS Code 的 settings 片段、检测脚本、以及 AI 修复的提示词模板。你不需要全部照搬，按自己项目的技术栈调整路径和规则即可。

3.1 VS Code settings.json 配置片段

在项目根目录的.vscode/settings.json里加入以下内容。这段配置做了三件事：指定无障碍检测脚本的路径、把 TaoToken 的环境变量注入、以及设置保存时自动检测。

{ "a11yCheck.scriptPath": "${workspaceFolder}/scripts/a11y-check.js", "a11yCheck.autoRunOnSave": true, "a11yCheck.include": ["src/**/*.vue", "src/**/*.jsx", "src/**/*.tsx"], "a11yCheck.exclude": ["**/node_modules/**", "**/dist/**"], "a11yCheck.taotoken.baseUrl": "https://taotoken.net/api", "a11yCheck.taotoken.apiKey": "${env:TAOTOKEN_API_KEY}", "a11yCheck.taotoken.modelId": "${env:TAOTOKEN_MODEL_ID}", "a11yCheck.fixPromptTemplate": "${workspaceFolder}/scripts/a11y-fix-prompt.md" }

注意a11yCheck.taotoken.baseUrl这里写的是完整地址，不要加/v1后缀，脚本内部会自己拼接。apiKey和modelId都通过环境变量读取，避免明文泄露。

如果你用的是 Cline 或类似插件做 MCP 集成，配置方式略有不同，但三件套不变：Base URL、Key、Model ID。Cline 的 MCP 配置里，把 TaoToken 作为一个 provider 写进去，Model ID 填同一个值即可。

3.2 检测脚本 a11y-check.js

在scripts/目录下新建a11y-check.js。这个脚本的作用是：读取当前打开的文件，抽取模板内容，跑一遍无障碍规则，把问题输出到控制台和 VS Code 的 Problems 面板。

const fs = require('fs'); const path = require('path'); // 简化版规则集，实际项目可替换为 axe-core const RULES = [ { id: 'img-alt', test: (node) => node.tag === 'img' && !node.attrs.alt, message: '图片缺少 alt 属性', severity: 'error' }, { id: 'button-name', test: (node) => node.tag === 'button' && !node.attrs['aria-label'] && !node.text, message: '按钮缺少可访问名称', severity: 'error' }, { id: 'color-contrast', test: (node) => node.style && node.style.color && node.style.background, message: '颜色对比度可能不足，建议检查', severity: 'warning' } ]; function parseTemplate(content) { // 简易解析，实际项目建议用 @vue/compiler-sfc const match = content.match(/<template>([\s\S]*?)<\/template>/); if (!match) return []; const template = match[1]; const nodes = []; const tagRegex = /<(\w+)([^>]*)>/g; let m; while ((m = tagRegex.exec(template)) !== null) { const tag = m[1]; const attrStr = m[2]; const attrs = {}; const attrRegex = /(\w[\w-]*)(?:="([^"]*)")?/g; let a; while ((a = attrRegex.exec(attrStr)) !== null) { attrs[a[1]] = a[2] || true; } nodes.push({ tag, attrs, text: '' }); } return nodes; } function checkFile(filePath) { const content = fs.readFileSync(filePath, 'utf-8'); const nodes = parseTemplate(content); const issues = []; nodes.forEach((node, index) => { RULES.forEach((rule) => { if (rule.test(node)) { issues.push({ file: filePath, line: index + 1, ruleId: rule.id, message: rule.message, severity: rule.severity }); } }); }); return issues; } const target = process.argv[2]; if (!target) { console.error('请传入要检测的文件路径'); process.exit(1); } const issues = checkFile(path.resolve(target)); if (issues.length === 0) { console.log('无障碍检测通过，未发现问题'); process.exit(0); } issues.forEach((issue) => { console.log(`${issue.file}:${issue.line} [${issue.severity}] ${issue.message} (${issue.ruleId})`); }); process.exit(1);

这个脚本是简化版，实际项目里建议直接引入axe-core，把解析后的 DOM 传进去跑。但结构是一样的：解析模板、跑规则、输出问题。你可以把它挂到 VS Code 的保存事件上，也可以单独在命令行跑。

3.3 AI 修复提示词模板 a11y-fix-prompt.md

在scripts/目录下新建a11y-fix-prompt.md。这个模板会被修复脚本读取，把问题代码和上下文一起发给 TaoToken。

你是一个前端无障碍修复专家。请根据以下信息，给出最小改动的修复方案。 ## 问题信息 - 规则 ID：{{ruleId}} - 问题描述：{{message}} - 文件路径：{{filePath}} - 行号：{{line}} ## 原始代码片段 ```html {{codeSnippet}}

修复要求

1. 只修改与无障碍相关的属性或标签，不要改动业务逻辑。
2. 如果缺少 alt，根据图片上下文给出合理描述；无法判断时用空 alt。
3. 如果缺少 aria-label，用简洁的中文描述控件用途。
4. 如果涉及颜色对比度，给出符合 WCAG AA 的色值建议。
5. 输出格式：先给出修复后的完整代码片段，再用一句话说明改动原因。

输出示例

<button aria-label="关闭弹窗">×</button>

改动原因：为图标按钮补充可访问名称，屏幕阅读器可正确朗读。

这个模板的关键是“最小改动”和“输出格式固定”。前者避免模型大改代码，后者方便脚本解析。你可以在模板里加更多规则，比如要求保留原有缩进、不引入新依赖等。 ### 3.4 修复脚本 fix-with-ai.js 再写一个脚本，把检测结果和提示词模板拼起来，调用 TaoToken 拿修复建议。 ```javascript const fs = require('fs'); const path = require('path'); const https = require('https'); const API_KEY = process.env.TAOTOKEN_API_KEY; const BASE_URL = process.env.TAOTOKEN_BASE_URL || 'https://taotoken.net/api'; const MODEL_ID = process.env.TAOTOKEN_MODEL_ID; async function callTaoToken(prompt) { const url = new URL(`${BASE_URL}/v1/chat/completions`); const body = JSON.stringify({ model: MODEL_ID, messages: [{ role: 'user', content: prompt }], temperature: 0.2 }); return new Promise((resolve, reject) => { const req = https.request( { hostname: url.hostname, path: url.pathname, method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${API_KEY}` } }, (res) => { let data = ''; res.on('data', (chunk) => (data += chunk)); res.on('end', () => { try { const json = JSON.parse(data); resolve(json.choices[0].message.content); } catch (e) { reject(new Error(`解析响应失败: ${data}`)); } }); } ); req.on('error', reject); req.write(body); req.end(); }); } async function fixIssue(issue, codeSnippet) { const template = fs.readFileSync( path.resolve(__dirname, 'a11y-fix-prompt.md'), 'utf-8' ); const prompt = template .replace('{{ruleId}}', issue.ruleId) .replace('{{message}}', issue.message) .replace('{{filePath}}', issue.file) .replace('{{line}}', issue.line) .replace('{{codeSnippet}}', codeSnippet); return callTaoToken(prompt); } module.exports = { fixIssue };

这个脚本不直接改文件，而是把修复建议返回给调用方。在 VS Code 插件里，你可以把返回内容展示在 Diff 视图里，让开发者确认后再应用。这样既用了 AI 的效率，又保留了人工审核的环节。

3.5 提交前校验：husky + lint-staged

在package.json里加入：

{ "scripts": { "a11y:check": "node scripts/a11y-check.js", "a11y:fix": "node scripts/fix-with-ai.js" }, "lint-staged": { "*.{vue,jsx,tsx}": [ "node scripts/a11y-check.js" ] } }

配合 husky 的 pre-commit 钩子，每次提交前自动跑检测。如果有 error 级别的问题，直接拦住提交，并在终端输出问题列表和修复建议。开发者可以选择手动改，也可以调用 AI 修复脚本生成建议。

这样一套下来，无障碍检查就从“想起来才做”变成了“提交前必过”。而且因为检测脚本和修复脚本共用同一套规则和提示词，团队里每个人的修复风格也趋于一致。

4. 验证请求与成功结果：修复前后评分对比

配置写完，得验证它真的能跑通。这一节我会用一个真实的 Vue 组件例子，走一遍从检测到修复再到复检的完整流程，并给出修复前后的无障碍评分变化。

4.1 准备一个有问题组件

新建src/components/UserCard.vue，内容如下：

<template> <div class="user-card"> <img :src="avatar" class="avatar"> <button class="close-btn" @click="close">×</button> <a href="/profile" class="profile-link">点击这里</a> <input type="text" placeholder="请输入昵称"> </div> </template> <script> export default { props: ['avatar'], methods: { close() { this.$emit('close'); } } }; </script> <style> .user-card { background: #f0f0f0; color: #999; } .close-btn { color: #ccc; background: #f0f0f0; } </style>

这个组件有几个典型问题：图片没有alt、关闭按钮没有可访问名称、链接文案“点击这里”含义不清、输入框没有关联标签、颜色对比度不足。

4.2 运行检测脚本

在终端执行：

node scripts/a11y-check.js src/components/UserCard.vue

输出类似：

src/components/UserCard.vue:3 [error] 图片缺少 alt 属性 (img-alt) src/components/UserCard.vue:4 [error] 按钮缺少可访问名称 (button-name) src/components/UserCard.vue:6 [warning] 颜色对比度可能不足，建议检查 (color-contrast)

如果配置了 VS Code 插件，保存文件时 Problems 面板也会出现对应提示，点击可以跳转到具体行。

4.3 调用 AI 修复

把检测结果传给修复脚本，或者直接在 VS Code 里点击 Quick Fix。以图片为例，发给 TaoToken 的提示词会包含：

规则 ID：img-alt 问题描述：图片缺少 alt 属性 文件路径：src/components/UserCard.vue 行号：3 原始代码片段：<img :src="avatar" class="avatar">

模型返回的修复建议类似：

<img :src="avatar" class="avatar" alt="用户头像">

改动原因：为图片补充描述性 alt，屏幕阅读器可正确朗读。

按钮的修复建议：

<button class="close-btn" @click="close" aria-label="关闭用户卡片">×</button>

链接文案的修复建议：

<a href="/profile" class="profile-link">查看个人资料</a>

输入框的修复建议：

<label for="nickname">昵称</label> <input id="nickname" type="text" placeholder="请输入昵称">

颜色对比度的修复建议：

.user-card { background: #f0f0f0; color: #333; } .close-btn { color: #333; background: #f0f0f0; }

4.4 应用修复并复检

把上述修改应用到组件里，再次运行检测脚本：

node scripts/a11y-check.js src/components/UserCard.vue

输出：

无障碍检测通过，未发现问题

如果用 axe-core 跑完整规则集，修复前的评分通常在 60-70 分左右，修复后可以到 95 分以上。具体分数取决于规则集和页面复杂度，但趋势是一致的：常见问题被消除后，评分会明显上升。

4.5 在 CI 里加一道校验

在.github/workflows/a11y.yml里加入：

name: Accessibility Check on: [pull_request] jobs: a11y: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm ci - run: node scripts/a11y-check.js src/components/UserCard.vue env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} TAOTOKEN_BASE_URL: https://taotoken.net/api TAOTOKEN_MODEL_ID: ${{ secrets.TAOTOKEN_MODEL_ID }}

这样每次 PR 都会跑一遍无障碍检测。如果有 error 级别的问题，CI 会失败，PR 无法合并。开发者可以在本地先用 AI 修复脚本生成建议，改完再提交。

注意 CI 里的环境变量通过 GitHub Secrets 注入，不要明文写在 workflow 文件里。Base URL 固定用https://taotoken.net/api，不要加 UTM 参数。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

配置过程中最容易卡在几个报错上。这一节把常见错误和排查路径列出来，你遇到时可以直接对照。

5.1 401 Unauthorized

报错原文：

{"error":{"message":"Invalid API key","type":"invalid_request_error"}}

原因通常是 Key 不对。排查顺序：

第一，检查.env.local里的TAOTOKEN_API_KEY有没有多余空格或换行。复制 Key 时容易带上首尾空白。

第二，确认 VS Code 的 settings.json 里引用的是${env:TAOTOKEN_API_KEY}，而不是写死的字符串。如果写死，改 Key 时容易漏改。

第三，确认 CI 里的 Secret 名称和 workflow 文件里引用的一致。GitHub Secrets 区分大小写。

第四，如果用的是 Cline 或 MCP 集成，检查配置文件里的 provider 字段是否指向 TaoToken，Base URL 是否填的https://taotoken.net/api。

5.2 local proxy failed

报错原文：

Error: local proxy failed to connect

这个错误通常出现在本地开发环境。原因可能是：

第一，本地网络无法直接访问https://taotoken.net/api。检查一下能不能用 curl 通。

第二，如果公司网络有代理设置，需要在环境变量里配置HTTPS_PROXY。注意这里说的是正常的网络代理配置，不是任何特殊工具。

第三，VS Code 的代理设置和终端不一致。可以在 VS Code 的 settings.json 里加"http.proxy"字段，值和你终端里的HTTPS_PROXY保持一致。

5.3 reading 'choices' of undefined

报错原文：

TypeError: Cannot read properties of undefined (reading 'choices')

这个错误说明 API 返回的结构和脚本预期的不一致。排查：

第一，打印完整响应体，看返回的 JSON 里有没有choices字段。如果返回的是错误信息，先解决错误。

第二，确认 Model ID 拼写正确。Model ID 错误时，有些接口会返回错误对象而不是标准响应。

第三，检查请求体里的messages格式。必须是数组，每个元素有role和content。

第四，如果用的是流式响应，需要按 SSE 格式解析，不能直接JSON.parse。

5.4 OAuth 相关报错

报错原文：

OAuth token expired or invalid

如果你用的是 Claude Code 或类似工具，可能会遇到 OAuth 报错。排查：

第一，确认你用的是 API Key 方式，而不是 OAuth 方式。TaoToken 的接入用 API Key 即可，不需要走 OAuth 流程。

第二，如果工具默认走 OAuth，在配置里切换为 API Key 模式。具体字段名看工具文档，通常是authType或credentialType。

第三，检查 Key 是否过期。在控制台重新生成一个，替换环境变量里的值。

5.5 修复建议不生效

有时候 AI 返回了修复建议，但应用到代码后检测仍然报错。原因可能是：

第一，修复建议只改了模板，没改样式。比如对比度问题需要同时改 CSS。

第二，Vue 的动态绑定语法没被正确解析。比如:alt="dynamicAlt"在检测脚本里可能被当成没有 alt。需要在解析逻辑里处理:前缀。

第三，修复后的代码没有保存，检测脚本读的是旧文件。

第四，缓存问题。VS Code 插件有时会缓存检测结果，重启窗口或手动触发一次检测。

5.6 CI 里 Key 不生效

CI 报 401，但本地正常。排查：

第一，确认 GitHub Secrets 里加了TAOTOKEN_API_KEY和TAOTOKEN_MODEL_ID。

第二，确认 workflow 文件里的env字段拼写正确，大小写一致。

第三，确认 Secret 的值没有多余空格。在 GitHub 界面里重新粘贴一次。

第四，如果用的是其他 CI 平台，检查环境变量注入方式是否一致。

6. 把无障碍检查变成日常研发习惯

整套链路跑通之后，你会发现无障碍检查不再是一个需要专门排期的任务。它变成了保存文件时的一次提示、提交前的一道校验、CI 里的一个步骤。开发者不需要记住所有规则，只需要在问题出现时看一眼修复建议，确认后应用即可。

如果你想把这件事在团队里推下去，建议从一个小项目开始。先配好 VS Code 的检测脚本和 AI 修复模板，让一两个同学试用一周。收集他们的反馈，调整提示词模板和规则集。等流程稳定了，再推广到更多项目。

几个实用技巧：

第一，把.env.local的模板放到项目 README 里，新同学 clone 下来填自己的 Key 即可。不要共用 Key，方便按人排查调用量。

第二，修复提示词模板里加上“保留原有缩进”和“不引入新依赖”这两条，能减少很多格式上的返工。

第三，CI 里先只拦 error 级别的问题，warning 先放行。等团队适应了，再逐步收紧。

第四，定期回顾检测结果，把高频问题沉淀成团队的无障碍编码规范。比如“所有图片必须有 alt”“所有图标按钮必须有 aria-label”，写进 Code Review 清单。

第五，如果你在用 Coding Plan 做长期编码或 Agent 任务，可以把无障碍检测脚本挂到 Agent 的工作流里，让它在生成代码后自动跑一遍检测。这样从生成到校验形成闭环，减少人工介入。

需要提醒的是，AI 修复建议不是万能的。对于复杂的交互组件，比如自定义下拉框、模态框、拖拽排序，模型可能给不出完全正确的方案。这时候还是需要开发者结合业务场景判断。AI 的作用是处理那些重复性高、规则明确的问题，把人的精力留给真正需要思考的部分。

最后，如果你还没开始用 TaoToken，可以先从模型对话页面试一下修复提示词的效果。确认模型能给出合理建议后，再接入到 VS Code 和 CI 里。接入文档里有完整的配置说明，API Keys 页面可以创建和管理 Key。长期做编码和 Agent 任务的团队，可以看看 Coding Plan 的额度方案，比按次调用更划算。

整套流程的核心就一句话：让无障碍问题在写代码的时候被发现，在提交之前被修复，在合并之前被验证。做到这三点，无障碍就不再是负担，而是研发流程里自然的一部分。