企业官网建设流程全解析

1. 注释规范为什么总在 PR 里翻车：前端 JSDoc 校验落地场景

前端团队定注释规范，最容易出现的情况是：文档里写得清清楚楚，代码里各写各的。有人用//顶在函数头上，有人写/** */但漏了@param，有人干脆不写。Code Review 时靠人肉盯，盯两次就疲了，最后规范变成"建议"。

我试过把注释规范拆成三层来落地：模板层（写什么）、规则层（怎么检查）、卡点层（什么时候拦）。三层缺一层，规范就会退化成口头约定。这篇文章就按这三层展开，重点放在可复制的 ESLint 配置、JSDoc 模板片段、本地与流水线验证命令，以及怎么用 TaoToken 统一 Key 把"注释生成/补全"这类辅助动作接进流程里，让规范从"约定"变成"可执行、可检查、可复现"。

先说清楚这套东西适合谁：中小前端团队、有 Code Review 流程但注释质量不稳定的项目、正在把 ESLint 从"只查语法"升级到"查文档质量"的仓库。如果你团队已经有eslint-plugin-jsdoc在用，但规则松松垮垮、CI 里没卡住，那这篇正好对得上。

核心检索词先摆出来：前端注释规范落地，本质是JSDoc 注释校验+ESLint 注释规则+CI 卡点三件套配合。JSDoc 是 JavaScript 生态里事实标准的文档注释格式，eslint-plugin-jsdoc能把它变成可检查的规则，CI 则决定"检查不过能不能合进去"。三者串起来，注释才有约束力。

为什么选 JSDoc 作为切入点而不是别的？因为它有结构化标签（@param、@returns、@example），机器能解析，规则能校验，IDE 能提示，三者天然对齐。纯文字注释没法自动检查，规范就只能靠自觉。而 JSDoc 的标签一旦缺失或类型写错，ESLint 能直接报出来，这就是"可检查"的基础。

落地时还有个现实问题：规则太严，老代码一开就红一片，团队会抵触；规则太松，等于没开。我的做法是分两步走——先对新文件、新函数开严格规则，老代码用overrides或注释豁免逐步迁移，等存量清得差不多再全量开。这个策略后面配置里会体现。

另外，注释生成这件事本身可以借助模型辅助：比如给一个函数签名，让模型按团队模板补出 JSDoc 骨架，人再改。这类调用需要一个统一的 API 通道和 Key 管理，避免每个人各自申请、各自配置、额度散落。TaoToken 在这里的角色就是统一入口——一个 Key、一个 Base URL，团队里谁要用辅助生成都走同一条通道，配置可复制、可审计。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end ，API 地址是 https://taotoken.net/api ，后面配置章节会给出具体写法。

这一节先把问题框住：注释规范落地难，难在"没有机器可执行的检查"。下一节讲前置准备——统一 Key 与通道怎么配，再往后才是规则和 CI。

2. TaoToken 前置：统一 Key 与 API 通道怎么配（含 Base URL 与模型 ID）

在写 ESLint 规则之前，先把"辅助生成注释"这条链路的前置条件配好。很多团队在这一步就散了：A 同学用某家 Key，B 同学用另一家，C 同学本地环境变量名都不一样，结果脚本跑不通、报错五花八门。统一 Key 和通道的价值就在这——配置只有一份，谁拉代码谁照抄。

TaoToken 的接入信息很简洁：API 根地址是https://taotoken.net/api，Key 在控制台的 API Keys 页面创建。注意这里不要加任何查询参数，Base URL 就是干净的/api结尾。模型 ID 按你实际要用的填，比如做注释补全这类文本任务，选一个通用对话模型即可，具体可用列表以控制台和文档为准，不要凭记忆硬编码。

三件套先对齐，这是后面所有配置的基础：

Key 的创建入口在控制台的 API Keys 页，文档在 doc 页。建议团队约定一个环境变量名，比如TAOTOKEN_API_KEY，所有人本地和 CI 都用同一个名字，脚本里只读这个变量。这样换人、换机器都不用改代码。

本地配置我一般写在 shell 的 profile 里，或者用.env配合 dotenv，但.env必须进.gitignore。CI 里则用仓库的 Secrets 注入同名变量。两条路径读同一个变量名，脚本零改动。

# 本地：写入 shell 配置（以 zsh 为例） echo 'export TAOTOKEN_API_KEY="sk-你的key"' >> ~/.zshrc source ~/.zshrc # 验证变量已生效（只回显前几位，避免泄露） echo "${TAOTOKEN_API_KEY:0:6}..."

如果你用 Node 脚本调注释生成，最小请求长这样，注意Authorization用 Bearer 格式，model换成你控制台里确认可用的 ID：

// scripts/gen-jsdoc.mjs const res = await fetch("https://taotoken.net/api/v1/chat/completions", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.TAOTOKEN_API_KEY}`, }, body: JSON.stringify({ model: "你的模型ID", messages: [ { role: "system", content: "你是前端注释助手，只输出 JSDoc 注释块，不要解释。" }, { role: "user", content: "为函数 add(a: number, b: number): number 生成 JSDoc" }, ], }), }); const data = await res.json(); console.log(data.choices?.[0]?.message?.content ?? data);

这段脚本的作用是"给签名、出注释骨架"，人再补业务语义。它不替代 ESLint 校验，只是降低写注释的启动成本。Key 统一之后，这个脚本在任何人机器上都能跑，CI 里也能作为可选的辅助步骤。

注意：Key 只走环境变量，不要写进.eslintrc、不要提交到仓库、不要贴进 issue。团队里如果有人把 Key 硬编码进脚本，Code Review 直接拦。

前置配完，下一节进入正题：ESLint 注释规则和 JSDoc 模板怎么写成可复制的配置。

3. 可复制配置：ESLint 注释规则 + JSDoc 模板 + settings 片段

这一节给三份可直接抄的东西：ESLint 配置片段、JSDoc 模板、以及辅助脚本的 settings。路径按常见项目结构写，你按自己仓库调整。

先装依赖。eslint-plugin-jsdoc是核心，配合 ESLint 9 的 flat config 或旧版.eslintrc都行，下面给 flat config 写法（eslint.config.js），旧项目可以对照迁移：

npm i -D eslint eslint-plugin-jsdoc

eslint.config.js片段，重点是规则取舍——先开"必须有 JSDoc"和"标签完整"，类型严格度按团队成熟度调：

// eslint.config.js import jsdoc from "eslint-plugin-jsdoc"; export default [ { files: ["src/**/*.{js,ts,vue}"], plugins: { jsdoc }, rules: { // 导出函数必须有 JSDoc "jsdoc/require-jsdoc": ["warn", { publicOnly: true, require: { FunctionDeclaration: true, MethodDefinition: true }, }], // 参数、返回值标签必须与签名一致 "jsdoc/require-param": "warn", "jsdoc/require-returns": "warn", // 参数描述不能为空 "jsdoc/require-param-description": "warn", "jsdoc/require-returns-description": "warn", // 标签顺序统一，避免各写各的 "jsdoc/tag-lines": ["warn", "any", { startLines: 1 }], // 类型写法统一（按需开启，老代码多可先关） "jsdoc/valid-types": "warn", }, }, { // 老代码目录先放宽，逐步迁移 files: ["src/legacy/**/*.js"], rules: { "jsdoc/require-jsdoc": "off" }, }, ];

JSDoc 模板按 excerpt 里的风格整理成团队版，函数、可选参数、返回值都覆盖到，直接贴进代码当骨架：

/** * 计算两个数的和，用于演示 JSDoc 模板 * 关联：无 * @param {number} a 第一个加数 * @param {number} b 第二个加数 * @param {number} [precision=2] 结果保留小数位，可选 * @returns {number} 两数之和 * @example * add(1, 2); // 3 */ export function add(a, b, precision = 2) { return Number((a + b).toFixed(precision)); }

文件头注释用 koroFileHeader 的配置，团队统一字段，避免有人写作者有人不写：

{ "fileheader.customMade": { "Author": "git config user.name", "Email": "git config user.email", "Description": "功能或页面描述", "Date": "Do not edit", "LastEditors": "git config user.name", "LastEditTime": "Do not edit" } }

辅助脚本的 settings 单独放一个scripts/comment-assist.config.json，把 Base URL、模型 ID、模板路径集中管理，Key 仍然只从环境变量读：

{ "baseUrl": "https://taotoken.net/api", "model": "你的模型ID", "templatePath": "./docs/jsdoc-template.md", "apiKeyEnv": "TAOTOKEN_API_KEY" }

这样配置的好处是：规则在 ESLint 里、模板在文档里、通道参数在 JSON 里，三处各管一摊，改哪块都不牵一发动全身。下一节验证这套东西真能跑起来。

4. 验证请求与成功结果：本地 lint、脚本调用、CI 三步走

配置写完不算数，得跑出结果。这一节给三条验证路径：本地 ESLint、辅助脚本调用、CI 流水线，每条都给命令和预期输出。

第一步，本地 lint 验证规则生效。故意写一个缺@param的函数，跑 lint 应该报 warn：

npx eslint src/utils/add.js

预期输出类似：

src/utils/add.js 3:1 warning Missing JSDoc @param "b" description jsdoc/require-param-description 3:1 warning Missing JSDoc @returns declaration jsdoc/require-returns

看到jsdoc/前缀的规则名，说明插件加载成功、规则命中。如果一条都不报，先查files匹配路径和publicOnly设置，导出函数才会被require-jsdoc盯上。

第二步，验证辅助脚本能通。用前面gen-jsdoc.mjs跑一次，成功时choices[0].message.content里应该是纯 JSDoc 块：

node scripts/gen-jsdoc.mjs

成功结果形如：

/** * 返回两数之和 * @param {number} a 第一个加数 * @param {number} b 第二个加数 * @returns {number} 和 */

如果返回的是 401 或一段错误 JSON，跳到下一节排障。这一步通了，说明 Base URL、Key、模型 ID 三件套对齐。

第三步，CI 卡点。在流水线里加一个 lint 步骤，规则从 warn 升到 error 才拦得住合并。建议新目录直接 error，老目录 warn：

# .github/workflows/lint.yml 片段 - name: Install run: npm ci - name: ESLint (comments) run: npx eslint "src/**/*.{js,ts,vue}" --max-warnings 0

--max-warnings 0是关键，warn 也会让步骤失败。等存量清完，把规则级别从 warn 改 error，卡点就硬了。CI 里如果要跑辅助脚本，记得把TAOTOKEN_API_KEY从 Secrets 注入，不要打印出来。

三步都过，说明"规则可执行、脚本可复现、CI 可拦截"这条链路成立。下一节专门收拾报错。

5. 常见错排查：401、local proxy failed、reading choices、OAuth 报错对照

跑不通的时候，报错信息往往指向不同层。这一节按真实报错对照排查，别一上来就怀疑规则写错。

401 Unauthorized：Key 没读到或格式不对。先确认环境变量在当前 shell 可见，再确认请求头是Bearer ${key}，中间有空格。CI 里常见是 Secrets 名字拼错，变量为空，请求自然 401。检查echo "${TAOTOKEN_API_KEY:0:6}..."有没有输出。

local proxy failed / 连接失败：这类多半是 Base URL 写错，比如多加了路径、少了/api、或者把带查询参数的地址填进了客户端。统一用https://taotoken.net/api，不要带 UTM 参数。客户端里如果要求填完整 endpoint，就在后面接/v1/chat/completions。

Cannot read properties of undefined (reading 'choices')：响应结构没按预期返回，通常是请求体字段错（比如model写了个不存在的 ID）或返回了错误对象。打印完整data再取choices，别直接链式访问。加个兜底：

const content = data?.choices?.[0]?.message?.content; if (!content) { console.error("响应异常：", JSON.stringify(data).slice(0, 300)); }

OAuth / 鉴权相关报错：如果你用的是带 OAuth 流程的客户端（比如某些编码工具），报错里出现 OAuth 字样，先确认该客户端是否支持自定义 Base URL 和 API Key 模式。支持的话切到 Key 模式，填三件套；不支持就换用直接 HTTP 调用的脚本，别在鉴权流程上死磕。

ESLint 规则不生效：报错里没有jsdoc/前缀，说明插件没加载。检查 flat config 里plugins是否注册、files是否匹配到目标文件、ESLint 版本是否支持该写法。旧版.eslintrc用extends: ["plugin:jsdoc/recommended"]对照迁移。

CI 里 lint 过、本地不过：多半是 Node 版本或依赖锁文件不一致。CI 用npm ci而不是npm install，本地也跑一次npm ci对齐。

排障的顺序建议是：先看 HTTP 层（401/连接），再看响应结构（choices），最后才看规则层。层与层之间别混着查，不然越查越乱。

6. 把注释规范接进日常：从 lint 到辅助生成的固定动作

规范落地到最后，拼的是"日常动作是否固定"。我的做法是把注释相关的事收敛成三个固定动作，团队照着做就行。

第一个动作：新函数先写 JSDoc 骨架再写实现。骨架可以直接用模板，也可以用辅助脚本生成后改。这一步的成本被压到最低，后面 lint 就不会红。

第二个动作：提交前本地跑一次npx eslint "src/**/*.{js,ts,vue}"，把 warn 清掉再推。CI 的--max-warnings 0是兜底，不是第一道防线。

第三个动作：每月清一次存量。用overrides圈出老目录，逐月缩小范围，直到全量开 error。存量清理不要一次全开，团队会被红海劝退。

辅助生成这条链路，Key 和通道统一之后，配置只有一份，谁都能复现。需要创建 Key 的去控制台 API Keys 页，接入细节看文档，想先验证模型效果可以直接在模型对话里试一段函数签名。长期做编码辅助和 Agent 流程的团队，Coding Plan 那条路径更适合把调用额度集中管理。三个入口按需选，别只记首页。

最后留一个实操建议：把docs/jsdoc-template.md和scripts/comment-assist.config.json一起提交进仓库，新人拉代码就能看到"注释长什么样、通道怎么配"，规范才算真正可复现。规则会过时、模板会调整，但"配置进仓库、Key 进环境变量"这条底线别破。