Next.js 文档同步实战：基于 update-docs 技能的代码变更到 docs/ 的完整维护工作流
【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js
本文以 Next.js 仓库内置的update-docsAgent 技能（.agents/skills/update-docs/SKILL.md）为主体，系统讲解"代码变更后如何同步更新官方文档"这一维护场景的完整工作流：从用git diff canary...HEAD分析变更、把源码路径映射到docs/下的 MDX 文件，到按仓库文档约定（frontmatter、代码块 switcher、Props 表格、<AppOnly>/<PagesOnly>）更新或新建文档，最后通过pnpm lint等命令完成校验。读完后，你可以照此流程独立完成一次 PR 级别的文档同步，并理解 Next.js 文档体系中 App Router 与 Pages Router 共享内容的source字段机制。
技能定位：这是给谁用的工作流
update-docs是 Next.js 仓库.agents/skills/目录下的一个内部 Agent 技能，其设计目标是在评审 PR 时检查并补齐文档完整性：针对当前分支相对canary的代码变更，引导 Agent 逐步完成"分析变更 → 定位受影响文档 → 逐项确认修改 → 校验格式 → 提交"的流程。技能的 frontmatter 声明如下（见 SKILL.md）：
--- name: update-docs description: This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", ... or mentions "docs/", "docs/01-app", "MDX", "API reference"... metadata: internal: true ---从 authoring-skills 技能 的规范可以看出，.agents/skills/下每个技能遵循统一结构：SKILL.md为必需入口（frontmatter + 正文），可选附带references/等补充文件。update-docs正是"hub + 细节"的典型例子：
- SKILL.md：主流程与快速参考；
- references/CODE-TO-DOCS-MAPPING.md：源码路径到文档路径的映射表；
- references/DOC-CONVENTIONS.md：frontmatter schema、代码块格式与 MDX 组件的完整规则。
description字段写得非常"触发词导向"——列出了 "update documentation for my changes"、"docs impact"、"scaffold docs for this feature" 等典型用户说法，这是 Agent 自动加载该技能的主要匹配依据。
五步总览（Quick Start）
技能给出的最小闭环是五步：
- 分析变更：运行
git diff canary...HEAD --stat查看本分支改了哪些文件； - 定位受影响文档：把变更的源码文件映射到
docs/下的文档路径； - 逐篇复核：与用户确认后再逐篇更新；
- 校验：运行
pnpm lint检查格式； - 提交：暂存文档变更。
其中第 4 步对应的命令脚本在仓库根目录 package.json 中确实存在，可直接执行：
pnpm lint # 完整 lint 检查（含类型、prettier-check、eslint 等） pnpm prettier-fix # 自动修复格式问题 pnpm types # TypeScript 检查从当前仓库的package.json可以看到，lint脚本实际是run-p test-types lint-typescript prettier-check "lint-eslint ." lint-ast-grep lint-language check-unused-turbo-tasks的组合，所以"文档改完跑pnpm lint"这一步同时覆盖了格式与文档相关的静态检查。
工作流一：分析代码变更
第一步：拿到 diff
# 查看本分支所有变更文件 git diff canary...HEAD --stat # 只看特定目录的变更 git diff canary...HEAD -- packages/next/src/这里以canary为基线，符合 Next.js 的分支模型：功能分支从canary切出，合回canary。
第二步：识别文档相关的变更
技能给出了一张"源码区域 → 文档影响"的判断表：
| 源码路径 | 可能的文档影响 |
|---|---|
packages/next/src/client/components/ | 组件 API 参考 |
packages/next/src/server/ | 函数 API 参考 |
packages/next/src/shared/lib/ | 视具体导出而定 |
packages/next/src/build/ | 配置或构建文档 |
packages/next/src/lib/ | 各类功能文档 |
第三步：映射到具体文档文件
映射细则收录在 CODE-TO-DOCS-MAPPING.md 中，例如：
src/client/components/image.tsx→docs/01-app/03-api-reference/02-components/image.mdxsrc/server/config-shared.ts→docs/01-app/03-api-reference/05-config/
Good to know：映射表是"起点"而非"权威"。从当前仓库结构看，映射表中个别源码路径指向的是历史布局——例如
packages/next/src/client/components/image.tsx在当前client/components/顶层目录中已不存在（组件实现被拆分到了更细的文件中），packages/next/src/client/use-client.ts、packages/next/src/server/use-server.ts等路径在当前顶层也查不到。因此执行映射时，技能自身也要求用"查找相关文档"的步骤（按导出名搜索docs/）二次确认，而不是机械照抄表格。docs/01-app/03-api-reference/02-components/image.mdx这个文档目标路径本身是真实存在的，可点开对照。
工作流二：更新现有文档
这是日常 PR 中最常用的路径，分五步：
Step 1：先读现有文档
修改前必须先了解目标文档的：
- 当前结构与章节划分；
- 使用了哪些 frontmatter 字段；
- 是否用
<AppOnly>/<PagesOnly>承载路由器特定内容。
Step 2：识别需要更新的内容
常见更新类型包括：
- 新增 props / 选项：加入 Props 表，并补一节用法说明；
- 行为变化：更新描述与示例；
- 废弃功能：加弃用提示和迁移指引；
- 新增示例：按仓库代码块约定添加代码块。
Step 3：逐条确认后再编辑
对每一处改动：先向用户展示计划改什么 → 等待确认 → 应用编辑 → 处理下一处。这是技能刻意设计的"低自动化"节奏，避免 Agent 一次性大面积重写文档。
Step 4：检查共享内容（source字段机制）
这是 Next.js 文档体系里最关键的机制之一：同一份 API 参考在 App Router 与 Pages Router 站点间共享内容，共享源在 App Router 一侧。Pages Router 侧的 MDX 通过 frontmatter 的source字段"拉取"App Router 的内容，例如：
# docs/02-pages/... 下使用共享内容的文件 --- source: app/building-your-application/optimizing/images ---规则是：要改的是 App Router 侧的源文件，而不是 Pages Router 侧的"消费者"文件。这个模式在真实文档中可以验证，例如 image.mdx 的正文开头就带有共享内容注释：
{/* The content of this doc is shared between the app and pages router. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. */}而 Pages Router 侧确实存在大量带source: app/api-reference的文件（当前位于docs/02-pages/04-api-reference/目录下，例如01-components/、04-config/中的多个 MDX）。DOC-CONVENTIONS.md 对此的表述是：source字段从 App Router 文档拉取内容，从而避免同一份 API 参考写两遍。
Step 5：校验变更
pnpm lint # 检查格式 pnpm prettier-fix # 自动修复格式问题工作流三：为新功能搭文档骨架
当新增的是一项完全没有文档的功能时，按"类型 → 位置 → 模板"三步走。
Step 1：确定文档类型与位置
| 功能类型 | 文档位置 | 使用模板 |
|---|---|---|
| 新组件 | docs/01-app/03-api-reference/02-components/ | API Reference |
| 新函数 | docs/01-app/03-api-reference/04-functions/ | API Reference |
| 新配置项 | docs/01-app/03-api-reference/05-config/ | Config Reference |
| 新概念 / 指南 | docs/01-app/02-guides/ | Guide |
| 新文件约定 | docs/01-app/03-api-reference/03-file-conventions/ | File Convention |
这些目录在当前仓库中全部真实存在：docs/01-app/03-api-reference/下包含01-directives、02-components、03-file-conventions、04-functions、05-config、06-cli等子目录（其中05-config下还有01-next-config-js/这样的细分目录），与技能给出的目录规划一致。
Step 2：文件命名
- 使用 kebab-case：
my-new-feature.mdx； - 需要控制展示顺序时加数字前缀：
05-my-new-feature.mdx； - 索引页统一命名
index.mdx； - 放入 Step 1 确定的目录。
Step 3：套用对应模板
API Reference 模板（注意共享内容注释、Props 表格的横向滚动包裹、TS/JS 双代码块 switcher）：
--- title: Feature Name description: Brief description of what this feature does. --- {/* The content of this doc is shared between the app and pages router. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} Brief introduction to the feature. ## Reference ### Props <div style={{ overflowX: 'auto', width: '100%' }}> | Prop | Example | Type | Status | | ----------------------- | ------------------ | ------ | -------- | | [`propName`](#propname) | `propName="value"` | String | Required | </div> #### `propName` Description of the prop. ```tsx filename="app/example.tsx" switcher // TypeScript example// JavaScript example**Guide 模板**（Prerequisites + 分步 + Next Steps）： ```mdx --- title: How to do X in Next.js nav_title: X description: Learn how to implement X in your Next.js application. --- Introduction explaining why this guide is useful. ## Prerequisites What the reader needs to know before starting. ## Step 1: First Step Explanation and code example. ```tsx filename="app/example.tsx" switcher // Code exampleStep 2: Second Step
Continue with more steps...
Next Steps
Related topics to explore.
### Step 4：补充 related 链接 在 frontmatter 中声明"下一步"相关链接，链接使用不带 `docs/` 前缀的站点路径： ```yaml related: title: Next Steps description: Learn more about related features. links: - app/api-reference/functions/related-function - app/guides/related-guide文档约定速查（Documentation Conventions）
完整规则在 DOC-CONVENTIONS.md，以下是可独立引用的要点。
Frontmatter
必填字段：
--- title: Page Title (2-3 words) description: One or two sentences describing the page. ---可选字段：
| 字段 | 用途 | 示例 |
|---|---|---|
nav_title | 导航侧边栏的更短标题 | nav_title: Image |
source | 从另一页拉取内容，避免重复 | source: app/api-reference/components/image |
related | "Next Steps" 区块 | 见上节 |
version | 开发阶段标识 | version: experimental |
version的取值语义：experimental（实验特性，可能变化）、legacy（遗留特性，考虑替代方案）、unstable（不稳定 API，不建议生产使用）、RC（发布候选）。
代码块约定
基本语法与属性：
```language filename="path/to/file.ext" code here ```| 属性 | 使用时机 | 示例 |
|---|---|---|
filename | 代码示例必须标注 | filename="app/page.tsx" |
switcher | 同时提供 TS 与 JS 变体 | switcher |
highlight | 高亮特定行 | highlight={1,3-5} |
TS/JS 切换块的固定顺序——TypeScript 在前，JavaScript 在后：
```tsx filename="app/page.tsx" switcher import type { Metadata } from 'next' export const metadata: Metadata = { title: 'My Page', }export const metadata = { title: 'My Page', }终端命令使用不带 `filename` 的 `bash` 块；行高亮支持 `highlight={1}`（单行）、`highlight={1,3}`（多行）、`highlight={1-5}`（区间）、`highlight={1,3-5,8}`（组合）。 ### 路由器特定内容 ```mdx <AppOnly> This content only appears in App Router documentation. </AppOnly> <PagesOnly> This content only appears in Pages Router documentation. </PagesOnly>约定文档特别提醒：组件内部要留空行，否则 Markdown 解析会出问题。
其他组件与格式
- 主题图片用
<Image srcLight="/docs/light/xxx.png" srcDark="/docs/dark/xxx.png" .../>提供明暗两套； - 提示块使用引用语法，单行
> **Good to know**: 内容，多行则在冒号后空一行再接列表； - Props 表格统一用
<div style={{ overflowX: 'auto', width: '100%' }}>包裹以支持移动端横向滚动；表格Status列取值为Required/-（可选）/Deprecated。
写作风格
- 指南类：指导性口吻，用 "you" 称呼读者；API 参考类：技术性口吻，使用祈使动词（create、pass、return）；
- 用具体指代："the
srcprop" 而不是 "this prop"； - 典型页面结构：简介 → 最小可用示例 → 详细参考/选项 → 分场景示例 → related 链接。
源码到文档的完整映射参考
CODE-TO-DOCS-MAPPING.md 把映射分成了几个维度，这里汇总核心内容。
精确文件级映射
组件：
| 源码路径 | 文档路径 |
|---|---|
packages/next/src/client/components/image.tsx | docs/01-app/03-api-reference/02-components/image.mdx |
packages/next/src/client/components/link.tsx | docs/01-app/03-api-reference/02-components/link.mdx |
packages/next/src/client/components/script.tsx | docs/01-app/03-api-reference/02-components/script.mdx |
packages/next/src/client/components/form.tsx | docs/01-app/03-api-reference/02-components/form.mdx |
函数：
| 源码路径 | 文档路径 |
|---|---|
packages/next/src/server/request/ | docs/01-app/03-api-reference/04-functions/ |
packages/next/src/server/lib/metadata/ | docs/01-app/03-api-reference/04-functions/generate-metadata.mdx |
packages/next/src/client/components/navigation.tsx | use-router/use-pathname/use-search-params三篇 mdx |
指令（Directives）：
| 源码路径 | 文档路径 |
|---|---|
packages/next/src/server/use-cache/ | docs/01-app/03-api-reference/01-directives/use-cache.mdx |
packages/next/src/client/use-client.ts | docs/01-app/03-api-reference/01-directives/use-client.mdx |
packages/next/src/server/use-server.ts | docs/01-app/03-api-reference/01-directives/use-server.mdx |
docs/01-app/03-api-reference/01-directives/目录在当前仓库中确实包含use-cache.mdx、use-client.mdx、use-server.mdx，映射目标侧是稳定的；而源码侧部分路径（如上所述）在仓库重构后会漂移，所以映射表要配合搜索确认使用。
配置：
| 源码路径 | 文档路径 |
|---|---|
packages/next/src/server/config-shared.ts | docs/01-app/03-api-reference/05-config/01-next-config-js/ |
packages/next/src/server/config.ts | docs/01-app/03-api-reference/05-config/01-next-config-js/ |
packages/next/src/build/webpack-config.ts | docs/01-app/03-api-reference/05-config/01-next-config-js/ |
其中 config-shared.ts 在当前仓库中真实存在，是所有next.config.js配置项（如 01-next-config-js 目录下的appDir.mdx、assetPrefix.mdx等）的类型与默认值定义源头——新增一个配置项，改这个文件，然后到01-next-config-js/下补一篇对应 mdx，这正是映射表"新配置项"模式的落地路径。
CLI：
| 源码路径 | 文档路径 |
|---|---|
packages/next/src/cli/next-dev.ts | docs/01-app/03-api-reference/06-cli/next-dev.mdx |
packages/next/src/cli/next-build.ts | docs/01-app/03-api-reference/06-cli/next-build.mdx |
packages/next/src/cli/next-start.ts | docs/01-app/03-api-reference/06-cli/next-start.mdx |
这三个 CLI 源文件在当前仓库的 packages/next/src/cli/ 目录下均可确认存在。
目录级映射
| 源码目录 | 文档区域 | 说明 |
|---|---|---|
packages/next/src/client/ | docs/01-app/03-api-reference/02-components/ | 客户端组件 |
packages/next/src/server/ | docs/01-app/03-api-reference/04-functions/ | 服务端函数 |
packages/next/src/build/ | docs/01-app/03-api-reference/05-config/ | 构建配置 |
packages/next/src/shared/lib/router/ | docs/01-app/02-guides/ | 路由指南 |
packages/next/src/lib/metadata/ | docs/01-app/02-guides/metadata/ | Metadata 指南 |
常见变更模式的落地路径
映射文档还给出了四类高频变更的处理套路：
- 新增 API 函数：在
packages/next/src/server/增加导出 → 在04-functions/建function-name.mdx→ 需要时更新索引页； - 新增组件 prop：改
client/components/下组件 → 更新对应文档的 Props 表 → 加一节带示例的 prop 说明； - 新增配置项：改
config-shared.ts→ 在05-config/01-next-config-js/找到相关文档 → 补描述与示例； - 行为变化：找到所有描述该行为的文档 → 同步描述与示例 → 若是破坏性变更，补迁移说明。
判断"改了什么"的第一步是看变更文件的导出：公共 API 导出对应 API Reference；内部工具函数通常无需文档；配置类型对应 Config 文档。再用两个搜索习惯收尾：在docs/下按关键词全文搜索（限定*.mdx）、按目录列文件（如docs/01-app/03-api-reference/04-functions/*.mdx），最后用source: app/api-reference在docs/02-pages/下 grep，确认是否存在 Pages Router 侧的共享消费者。
提交前的校验清单
技能给出的最终 checklist，可原样作为 PR 自检项使用：
- Frontmatter 有
title和description - 代码块都带
filename属性 - TypeScript 示例带
switcher且提供 JS 变体 - Props 表格格式正确（含横向滚动包裹）
- Related 链接指向有效路径
pnpm lint通过- 如有预览环境，确认页面渲染正确
小结
update-docs技能的价值在于把 Next.js 文档维护中"隐性知识"显性化：哪类源码变更影响哪类文档（映射表）、同一份内容如何在两个路由器站点间共享（source字段 +<AppOnly>/<PagesOnly>）、文档长什么样才算合规（frontmatter、switcher 代码块、Props 表约定），以及如何自证合规（pnpm lint/pnpm prettier-fix/pnpm types）。对仓库维护者来说，这三份文件（SKILL.md、DOC-CONVENTIONS.md、CODE-TO-DOCS-MAPPING.md）本身就是一份可直接执行的文档风格指南；而对普通读者，理解这套约定也能解释你在 Next.js 官方文档中看到的每一个细节——为什么 TS/JS 示例可以切换、为什么某些页面在 App 与 Pages 站点长得一样、为什么配置参考都集中在01-next-config-js/一个目录里。
【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
