Next.js 文档维护：CODE-TO-DOCS-MAPPING 源码到文档映射表实战指南
Next.js 文档维护CODE-TO-DOCS-MAPPING 源码到文档映射表实战指南【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js本文以 Next.js 仓库中update-docs技能的核心参考文件 CODE-TO-DOCS-MAPPING.md 为主体完整解读“源码目录 → 文档文件”的映射规则、三步定位相关文档的流程、四类常见变更的文档更新模式与快速搜索命令并结合当前仓库源码逐一核验各映射路径的落地情况帮助维护者以及 AI Agent在修改代码后快速判断哪些文档需要同步更新、更新到哪个文件、按什么规范更新。一、映射文档的定位update-docs 技能的“导航图”在 Next.js 仓库中.agents/skills/目录存放了一组面向维护者和 AI Agent 的技能定义。其中 SKILL.md 定义了 “Next.js Documentation Updater” 工作流当用户要求“检查这个 PR 的文档”“同步代码与文档”“评估文档影响面”时Agent 会按照 Quick Start 执行Analyze changes运行git diff canary...HEAD --stat查看当前分支相对 canary 分支的变更文件Identify affected docs将变更的源码文件映射到文档路径——这一步依赖的正是 CODE-TO-DOCS-MAPPING.mdReview each doc逐份确认更新内容Validate运行pnpm lint检查格式Commit提交文档变更。因此映射文档解决的是一个高频问题当packages/next/src/下某个文件发生变化时docs/下哪个.mdx文件应该被同步修改该文件开篇即声明其职责“Maps Next.js source code directories to their corresponding documentation files.”将 Next.js 源码目录映射到对应的文档文件。配套的 DOC-CONVENTIONS.md 则规定了文档本身的写法frontmatter 字段、代码块filename/switcher属性、AppOnly/PagesOnly组件、Props 表格格式等两者一个管“找到文档”一个管“写好文档”。二、核心映射表Core Mappings映射表按 API 形态分为六组Components、Functions、File Conventions、Configuration、Directives、Metadata File Conventions。以下完整继承原文档的映射内容并补充源码核验结论。2.1 Components 组件源码路径文档路径packages/next/src/client/components/image.tsxdocs/01-app/03-api-reference/02-components/image.mdxpackages/next/src/client/components/link.tsxdocs/01-app/03-api-reference/02-components/link.mdxpackages/next/src/client/components/script.tsxdocs/01-app/03-api-reference/02-components/script.mdxpackages/next/src/client/components/form.tsxdocs/01-app/03-api-reference/02-components/form.mdx文档侧可以确认 docs/01-app/03-api-reference/02-components/ 目录下确实存在image.mdx、link.mdx、script.mdx、form.mdx四个文件与映射一一对应。从当前源码结构看组件实现文件的实际位置相对映射表已有调整next/image的实现位于 legacy/image.tsx而非映射表所写的client/components/image.tsxlink与form则分别有packages/next/src/client/link.tsx、packages/next/src/client/app-dir/link.tsx以及packages/next/src/client/form.tsx、packages/next/src/client/app-dir/form.tsx两套实现legacy 与 App Router 各一份script位于packages/next/src/client/script.tsx。这说明该映射表更适合作为“文档定位线索”而非精确文件索引——当映射路径失效时以grep/find在packages/next/src/下按导出名检索为准。2.2 Functions 函数源码路径文档路径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.mdxpackages/next/src/client/components/navigation.tsxdocs/01-app/03-api-reference/04-functions/use-router.mdxpackages/next/src/client/components/navigation.tsxdocs/01-app/03-api-reference/04-functions/use-pathname.mdxpackages/next/src/client/components/navigation.tsxdocs/01-app/03-api-reference/04-functions/use-search-params.mdx这组映射在源码中得到了充分印证packages/next/src/server/request/ 目录存在包含cookies.ts、headers.ts、draft-mode.ts、pathname.ts、search-params.ts、params.ts等文件它们正是 docs/01-app/03-api-reference/04-functions/ 下cookies.mdx、headers.mdx、draft-mode.mdx、next-request.mdx等 API 文档的对应实现navigation.ts实际扩展名为.ts而非映射表所写的.tsx通过export function导出了useSearchParams约 L55、usePathname约 L112、useRouter约 L166、useParams约 L215、useSelectedLayoutSegments、useSelectedLayoutSegment等 Hook——即“一个源码文件对应多个函数文档”的典型例子同一文件中的不同导出各自映射到use-router.mdx、use-pathname.mdx、use-search-params.mdx、use-params.mdx等独立文档。值得注意的是packages/next/src/server/lib/metadata/在当前仓库中已不存在metadata 相关实现resolve-metadata.ts、get-metadata-route.ts、generate/等实际位于 packages/next/src/lib/metadata/与后文“By Feature Area”表中packages/next/src/lib/metadata/的条目相互印证。2.3 File Conventions 文件约定源码路径文档路径packages/next/src/build/webpack/loaders/docs/01-app/03-api-reference/03-file-conventions/packages/next/src/server/app-render/docs/01-app/03-api-reference/03-file-conventions/layout.mdxpackages/next/src/server/app-render/docs/01-app/03-api-reference/03-file-conventions/page.mdx两个源码目录在当前仓库中均已确认存在packages/next/src/build/webpack/loaders/存放各文件类型的 webpack 加载器即layout.js、page.js等约定文件如何被识别与编译的入口packages/next/src/server/app-render/负责 App Router 的服务端渲染管线。文档侧 docs/01-app/03-api-reference/03-file-conventions/ 目录下可确认存在layout.mdx、page.mdx以及error.mdx、loading.mdx、not-found.mdx、intercepting-routes.mdx、dynamic-routes.mdx、01-metadata/等映射关系成立。2.4 Configuration 配置源码路径文档路径packages/next/src/server/config-shared.tsdocs/01-app/03-api-reference/05-config/01-next-config-js/packages/next/src/server/config.tsdocs/01-app/03-api-reference/05-config/01-next-config-js/packages/next/src/build/webpack-config.tsdocs/01-app/03-api-reference/05-config/01-next-config-js/三个源码文件均确认存在。它们构成next.config.js的处理链config-shared.ts定义配置项类型与默认值config.ts负责读取与归一化用户配置webpack-config.ts将配置落到 webpack 构建行为上。文档侧 docs/01-app/03-api-reference/05-config/01-next-config-js/ 采用“一个配置项一篇文档”的粒度可确认存在appDir.mdx、basePath.mdx、assetPrefix.mdx、allowedDevOrigins.mdx、cacheComponents.mdx、cacheHandlers.mdx等文件——即源码中新增/变更的配置项都要落到这个目录下的对应.mdx中。2.5 Directives 指令源码路径文档路径packages/next/src/server/use-cache/docs/01-app/03-api-reference/01-directives/use-cache.mdxpackages/next/src/client/use-client.tsdocs/01-app/03-api-reference/01-directives/use-client.mdxpackages/next/src/server/use-server.tsdocs/01-app/03-api-reference/01-directives/use-server.mdx从当前源码结构看packages/next/src/server/use-cache/目录确实存在含cache-life.ts、cache-tag.ts、handlers.ts等文件与use-cache.mdx的映射成立而use client/use server指令本身并不以独立文件use-client.ts、use-server.ts的形式存在源码中更接近的是如 use-client-disallowed.ts 这样的辅助模块指令更多在编译器/构建层Rust crates 与 loaders中被识别。文档侧 docs/01-app/03-api-reference/01-directives/ 下可确认存在use-cache.mdx、use-client.mdx、use-server.mdx三个文档。因此指令类文档的“源码映射”应理解为“指令语义在源码中的主要承载位置”而非单一入口文件。2.6 Metadata File Conventions 元数据文件约定源码路径文档路径packages/next/src/lib/metadata/docs/01-app/03-api-reference/03-file-conventions/01-metadata/Metadata icons handlingdocs/01-app/03-api-reference/03-file-conventions/01-metadata/app-icons.mdxOpen Graph imagesdocs/01-app/03-api-reference/03-file-conventions/01-metadata/opengraph-image.mdxSitemap generationdocs/01-app/03-api-reference/03-file-conventions/01-metadata/sitemap.mdxpackages/next/src/lib/metadata/目录已确认存在内含metadata.tsx、resolve-metadata.ts、get-metadata-route.ts、is-metadata-route.ts、resolvers/、generate/等文件负责metadata.js、opengraph-image、sitemap等约定文件的解析与路由注册文档侧docs/01-app/03-api-reference/03-file-conventions/01-metadata/目录同样存在。三、目录级模式映射Directory Pattern Mappings除精确到文件的映射外映射文档还给出两套粗粒度规则用于处理表中没有覆盖的情况。3.1 按功能区域By Feature Area源码目录文档区域说明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/元数据指南这五个源码目录在仓库中全部确认存在。可以看出文档目录结构02-components、04-functions、05-config、02-guides与源码的职责划分client / server / build / shared / lib是刻意对齐的——这种对齐正是“看目录就能定位文档”这一方法成立的前提。3.2 CLI 命令源码路径文档路径packages/next/src/cli/next-dev.tsdocs/01-app/03-api-reference/06-cli/next-dev.mdxpackages/next/src/cli/next-build.tsdocs/01-app/03-api-reference/06-cli/next-build.mdxpackages/next/src/cli/next-start.tsdocs/01-app/03-api-reference/06-cli/next-start.mdx三个 CLI 入口文件均已确认存在于packages/next/src/cli/下。可以推断CLI 子命令的行为变更参数、输出、退出码都应同步到 docs/01-app/03-api-reference/06-cli/ 下对应的.mdx该目录当前可确认包含next.mdx、create-next-app.mdx、index.mdx。四、三步定位相关文档Finding Related Documentation映射表无法覆盖所有场景映射文档随后给出一个通用的三步骤检索流程Step 1识别变更的导出Identify the changed export观察被修改文件导出了什么据此判断文档归属Public API exports公共 API 导出→ API Reference 文档Internal utilities内部工具→ 通常无需文档Configuration types配置类型→ Config 文档。Step 2搜索已有文档Search for existing docs利用 Agent 的内置搜索工具查找提及某术语的文档用 Grep 类工具以目标术语为 pattern、docs/为搜索路径列出某目录下的文档用 Glob 类工具pattern 形如docs/01-app/03-api-reference/04-functions/*.mdx。Step 3检查共享内容Check for shared content如果正在编辑 App Router 文档需要检查 Pages Router 是否存在带source字段的对应文件。用 Grep 在docs/02-pages/下搜索 patternsource: app/api-reference。这一点在当前仓库中有大量实例可证grep ^source: app/ docs/02-pages/可命中 multi-zones.mdx、analytics.mdx、self-hosting.mdx 等文件。source字段的工作机制在 DOC-CONVENTIONS.md 中有完整说明Pages Router 文档通过source: app/api-reference/components/image这类字段从 App Router 文档“拉取”内容从而避免两份文档重复维护。结论当发现source指向共享文档时应编辑 App Router 侧的源文件而不是 Pages Router 侧的消费文件。五、四类常见变更的文档更新模式Common Patterns映射文档沉淀了四类变更场景的标准操作序列5.1 新增 API 函数New API Function在packages/next/src/server/中新增了导出在docs/01-app/03-api-reference/04-functions/function-name.mdx创建文档视情况更新 index/列表页。5.2 新增组件 PropNew Component Prop在packages/next/src/client/components/的组件中新增 Prop在对应文档的 Props 表格中补充该行新增一节解释该 Prop 并附示例。以 image.mdx 为例其正文开头的共享内容注释“The content of this doc is shared between the app and pages router...”与 Props 表格 逐 Prop 小节#### \propName的结构正是该模式要求维护的目标形态。5.3 新增配置项New Config Option选项被加入packages/next/src/server/config-shared.ts在docs/01-app/03-api-reference/05-config/01-next-config-js/下找到相关配置文档补充该选项的说明与示例。5.4 行为变更Behavioral Change任意源码文件的逻辑发生变化找出所有描述该行为的文档更新描述与示例以匹配新行为若是破坏性变更添加迁移说明migration notes。这四类模式与update-docs技能定义的前置检查清单frontmatter 是否含title/description、代码块是否有filename属性、TypeScript 示例是否配switcher与 JS 变体、Props 表格格式、related 链接有效性、pnpm lint是否通过配套使用构成“改代码 → 定文档 → 写文档 → 验证”的闭环。六、快速搜索命令Quick Search Commands映射文档末尾给出四条高频检索方式均基于 Agent 内置工具查找提及某术语的所有文档Grep 工具 搜索 pattern 路径docs/过滤*.mdx文件列出所有 API reference 文档Glob 工具 patterndocs/01-app/03-api-reference/**/*.mdx按文件名模式查找文档Glob 工具 pattern 如docs/**/*image*.mdx读取文档 frontmatterRead 工具 行数限制重点检查source字段。在命令行环境下等价做法例如在仓库根目录执行rg -l 某术语 docs --glob *.mdx、find docs/01-app/03-api-reference -name *.mdx等。七、映射表的时效性结合当前仓库的核验结论将映射表与当前仓库逐一比对后可总结出以下使用经验均基于源码结构核验映射条目核验结果client/components/navigation.tsx实际文件为packages/next/src/client/components/navigation.ts.ts扩展名其中useRouter/usePathname/useSearchParams导出与三份函数文档一一对应client/components/image.tsx实际实现位于packages/next/src/client/legacy/image.tsxlink.tsx/form.tsx各有 legacy 与app-dir/两套实现server/lib/metadata/目录已不存在metadata 实现位于packages/next/src/lib/metadata/client/use-client.ts/server/use-server.ts无同名独立文件指令语义由编译器/构建层承载文档仍存在于01-directives/server/request/、build/、app-render/、use-cache/、shared/lib/router/、CLI 三件套全部确认存在映射成立由此可以推断该映射表的定位它是一份**“文档影响面速查表”**给出的是高概率起点而非强保证。当按表中路径找不到文件时正确做法是回到映射文档 Step 1–2 的方法——按导出名在packages/next/src/下检索、按术语在docs/下检索——而不是放弃定位。八、小结把“代码变更”翻译成“文档工单”的工作流综合映射文档全文一次完整的“代码变更 → 文档同步”操作可归纳为git diff canary...HEAD --stat拿到变更文件清单优先查核心映射表第二、三节组件 →02-components/、服务端函数 →04-functions/、配置 →05-config/01-next-config-js/、指令 →01-directives/、约定文件 →03-file-conventions/、CLI →06-cli/表中未命中时走三步检索流程按导出类型判断归属 → Glob/Grep 定位既有文档 → 检查source:共享字段按四类 Common Patterns 确定更新动作新建文档 / 补 Props 表 / 补配置项 / 修订行为描述并加迁移说明遵循 DOC-CONVENTIONS.md 的格式规范frontmatter、filename/switcher代码块、AppOnly/PagesOnly、Props 表格最后用pnpm lint验证。这套映射机制的价值在于Next.js 文档树docs/01-app/与docs/02-pages/的目录结构与packages/next/src/的模块划分刻意对齐维护者无需通读代码库仅凭变更文件所在目录与导出形态就能在秒级定位需要更新的文档文件及其格式约束。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考