Qwen Code 文档站搭建指南基于 Next.js Nextra 的公开文档站点实战【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文围绕 Qwen Code 仓库中的 docs-site/README.md 展开深入讲解如何用 Next.js 与 Nextra 构建、配置并运行一个独立的公开文档站点。你将掌握从依赖安装、公开内容链接link到开发服务器启动的完整流程并理解该站点如何通过「内容白名单 符号链接 静态路由过滤」机制只对外发布docs目录下的用户指南users与开发者指南developers而将内部规划、设计与 E2E 笔记隔离在站点内容树之外——这套「单仓库多内容分区」的打法可直接复用到你自己的开源项目文档站建设中。一、项目概览为什么需要独立的 docs-siteQwen Code 是一个运行在终端里的开源 AI 编程代理agentic coding tool。它的文档非常庞大docs 目录下既包含面向终端用户与贡献者的公开文档也包含大量内部规划、设计与 E2E 验证笔记例如 docs/design 下的数十篇设计文档。如果直接把整个docs目录全部发布到文档站内部草稿就会泄漏到公网。因此仓库专门拆出了一个 docs-site 子目录作为独立的文档网站工程站点本体只包含 Next.js 应用骨架路由、布局、MDX 组件配置公开文档内容并不复制进站点而是通过符号链接symlink方式按需引入站点通过路由层过滤确保任何指向内部文档的 URL 都返回 404。从仓库结构看docs-site 是一个完全自包含的 npm 工程拥有自己的 package.json、next.config.mjs、vitest.config.js可以独立安装、独立测试、独立部署。二、技术栈与依赖根据 docs-site/package.json站点基于以下核心依赖依赖版本以 package.json 为准作用next^16.0.8应用框架与静态站点生成SSGnextra^4.6.1MDX 内容引擎与页面加载nextra-theme-docs^4.6.1文档站主题导航栏、侧边栏、页脚react/react-dom^19.2.1前端运行时vitest^3.2.4dev单元测试next.config.mjs的配置非常精简仅用 Nextra 包装默认配置import nextra from nextra; const withNextra nextra({}); export default withNextra({});而 mdx-components.js 则负责把 Nextra 文档主题的默认 MDX 组件如pre、code、table等与自定义组件合并import { useMDXComponents as getThemeComponents } from nextra-theme-docs; const themeComponents getThemeComponents(); export function useMDXComponents(components) { return { ...themeComponents, ...components, }; }环境要求README 明确指出需要 Node.js 18 与 npm 或 yarn。这与 Next.js 16 的运行时要求一致安装前请先确认node -v满足版本要求。三、安装与内容准备3.1 安装依赖在仓库根目录下进入文档站工程并安装依赖cd docs-site npm install3.2 链接公开文档内容关键步骤文档站的内容并不直接放在站点目录内而是来自父级docs目录。执行npm run link该命令对应 package.json 中的脚本link: node scripts/link-public-docs.mjs实际由 scripts/link-public-docs.mjs 完成。其核心逻辑为删除并重建站点内的content目录复制docs/index.md与docs/_meta.ts作为站点首页与导航元数据遍历公开内容根白名单PUBLIC_DOC_ROOTS将docs下对应子目录以符号链接方式挂到content下。白名单定义在 src/app/public-docs.jsexport const PUBLIC_DOC_ROOTS [users, developers];即只有docs/users用户指南与docs/developers开发者指南会进入公开站点内容树docs/design、docs/plans、docs/e2e-tests等内部规划、设计、E2E 笔记保持在站点内容树之外。3.3 开发服务器npm run dev该脚本先执行npm run clean清理.next构建缓存再以 Turbopack 启动开发服务器dev: npm run clean next --turbopack启动后在浏览器打开http://localhost:3000即可预览文档站。README 中明确给出了该访问地址。四、项目结构与路由机制README 给出了站点目录结构结合仓库源码可进一步还原完整结构docs-site/ ├── scripts/ │ └── link-public-docs.mjs # 内容链接脚本 ├── src/ │ └── app/ │ ├── [[...mdxPath]]/ # MDX 页面动态路由 │ │ ├── page.jsx # 页面组件 静态参数生成 │ │ └── page.test.jsx # 路由过滤测试 │ ├── layout.jsx # 根布局导航栏、横幅、页脚 │ ├── public-docs.js # 公开内容白名单与路径判定 │ └── public-docs.test.js # 白名单逻辑测试 ├── mdx-components.js # MDX 组件配置 ├── next.config.mjs # Next.js 配置 ├── package.json └── vitest.config.js4.1 动态路由[[...mdxPath]]src/app/[[...mdxPath]]/page.jsx 使用 Nextra 提供的generateStaticParamsFor(mdxPath)生成全部静态页面参数并通过filterPublicStaticParams过滤只保留公开路径export const dynamicParams false; export async function generateStaticParams(...args) { const staticParams await generateAllStaticParams(...args); return filterPublicStaticParams(staticParams); }dynamicParams false意味着未在静态参数列表中的路径一律不渲染从构建层面杜绝内部文档被发布。同时页面组件在渲染前还会调用isPublicDocsPath二次校验不通过则notFound()。4.2 公开路径判定逻辑public-docs.js 中的判定函数支持多语言前缀LOCALE_SEGMENTS定义了en、zh、de、fr、ja、ru、pt-BR等语言段路径首个段若是语言代码则跳过再看第二个段是否属于白名单const LOCALE_SEGMENTS new Set([en, zh, de, fr, ja, ru, pt-BR]); const PUBLIC_DOC_ROOT_SET new Set(PUBLIC_DOC_ROOTS); function publicRootFromSegments(segments []) { if (segments.length 0 || (segments.length 1 segments[0] )) { return undefined; } const rootIndex LOCALE_SEGMENTS.has(segments[0]) ? 1 : 0; return segments[rootIndex]; } export function isPublicDocsPath(mdxPath []) { const root publicRootFromSegments(mdxPath); return root undefined || PUBLIC_DOC_ROOT_SET.has(root); }路径判定矩阵由 public-docs.test.js 的用例可直接印证mdxPath是否公开说明[]/[]✅站点首页[users, foo]✅用户指南下任意页面[en, users]✅带语言前缀的公开页[design, bar]❌内部设计文档拒绝发布[plans]❌内部规划文档拒绝发布4.3 失败关闭fails closed设计public-docs.test.js 与 page.test.jsx 都覆盖了一个关键防御场景当 Nextra 未来改变了静态参数的数据结构例如从mdxPath变为slug时过滤逻辑会直接抛出 TypeError 而不是静默放行it(fails closed if Nextra changes the static params shape, () { expect(() filterPublicStaticParams([{ slug: [users] }])).toThrow( Expected generateStaticParamsFor(mdxPath) to return objects with an mdxPath array., ); });这是一种「失败关闭」的安全策略宁可构建失败也不允许内部文档意外流入公开站点。五、根布局与主题配置src/app/layout.jsx 使用nextra-theme-docs提供完整的文档站布局包含横幅、导航栏、侧边栏与页脚const banner ( Banner storageKeysome-keyQwen Code 0.5.0 is released /Banner ); const navbar ( Navbar logo{bQwen Code/b} / ); const footer FooterMIT {new Date().getFullYear()} © Qwen Team./Footer;几个值得注意的配置点pageMap{await getPageMap()}Nextra 根据content目录中的_meta.ts复制自 docs/_meta.ts自动生成导航页图。_meta.ts定义了三个顶层条目隐藏的index首页、usersUser Guide、developersDeveloper Guide侧边栏只会展示这两大公开分区sidebar{{ defaultMenuCollapseLevel: 9999 }}用超大有限整数代替Infinity让所有侧边栏目录默认全部展开注释说明某些 schema 校验器会拒绝Infinitysearch{false}当前关闭了内置搜索docsRepositoryBase指向文档源码仓库的docs目录供「编辑此页」跳转使用HTML 层面设置了langen、dirltr并带suppressHydrationWarning以配合next-themes主题切换。页面渲染时page.jsx 通过importPage(params.mdxPath)加载 MDX 内容、目录toc与元数据并交给主题Wrapper渲染const { default: MDXContent, toc, metadata, sourceCode } await importPage(params.mdxPath); return ( Wrapper toc{toc} metadata{metadata} sourceCode{sourceCode} MDXContent {...props} params{params} / /Wrapper );同时通过generateMetadata将页面 frontmatter 中的 metadata 透出用于 SEO。六、测试体系站点配套了基于 Vitest 的单元测试vitest.config.js 只收集src/**/*.test.{js,jsx}npm test现有两个测试文件覆盖两条核心安全边界public-docs.test.js验证isPublicDocsPath的多语言路径判定矩阵以及filterPublicStaticParams能正确过滤掉design、plans等内部路径、保留users/developers公开路径page.test.jsxmock 掉nextra/pages后验证generateStaticParams在构建期同样只产出公开路径并验证失败关闭行为。七、从 README 到生产部署实操要点总结把 docs-site/README.md 的操作步骤串联成一条可复用的完整流程# 1. 安装依赖Node.js 18 cd docs-site npm install # 2. 准备公开内容生成 content/ 目录 npm run link # 3. 本地开发预览http://localhost:3000 npm run dev # 4. 运行安全边界测试 npm test几个实际使用中的要点每次内容变更后需重新执行npm run link因为content目录每次都会被重建rmmkdir 重新cp/symlink新建的公开文档才会被纳入站点新增公开分区需要同步改两处一是 docs/_meta.ts 增加顶层条目二是 docs-site/src/app/public-docs.js 的PUBLIC_DOC_ROOTS加入对应目录名源码注释明确要求两者保持同步且 scripts/link-public-docs.mjs 消费同一个白名单内部文档天然隔离docs/design、docs/plans、docs/e2e-tests等目录既不会被链接进content又会被静态路由过滤拒绝形成双重保险部署形态next.config.mjs未做任何自定义输出配置直接使用 Next.js 默认构建即可产出可部署的静态站点产物next build适合托管到各类静态站点平台。八、总结Qwen Code 的 docs-site 展示了一种干净利落的「单仓库双内容域」文档站组织方式用独立 Next.js 工程承载站点骨架用符号链接按需挂载公开文档再用「构建期静态参数过滤 运行期路径判定 失败关闭测试」三重机制守住内部内容不外泄的边界。无论你是想为开源项目搭建官方文档站还是需要在巨型 monorepo 中隔离公开与内部文档这套基于 Next.js 16 Nextra 4 的方案都值得直接参考与复用。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Qwen Code 文档站搭建指南：基于 Next.js + Nextra 的公开文档站点实战
Qwen Code 文档站搭建指南基于 Next.js Nextra 的公开文档站点实战【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文围绕 Qwen Code 仓库中的 docs-site/README.md 展开深入讲解如何用 Next.js 与 Nextra 构建、配置并运行一个独立的公开文档站点。你将掌握从依赖安装、公开内容链接link到开发服务器启动的完整流程并理解该站点如何通过「内容白名单 符号链接 静态路由过滤」机制只对外发布docs目录下的用户指南users与开发者指南developers而将内部规划、设计与 E2E 笔记隔离在站点内容树之外——这套「单仓库多内容分区」的打法可直接复用到你自己的开源项目文档站建设中。一、项目概览为什么需要独立的 docs-siteQwen Code 是一个运行在终端里的开源 AI 编程代理agentic coding tool。它的文档非常庞大docs 目录下既包含面向终端用户与贡献者的公开文档也包含大量内部规划、设计与 E2E 验证笔记例如 docs/design 下的数十篇设计文档。如果直接把整个docs目录全部发布到文档站内部草稿就会泄漏到公网。因此仓库专门拆出了一个 docs-site 子目录作为独立的文档网站工程站点本体只包含 Next.js 应用骨架路由、布局、MDX 组件配置公开文档内容并不复制进站点而是通过符号链接symlink方式按需引入站点通过路由层过滤确保任何指向内部文档的 URL 都返回 404。从仓库结构看docs-site 是一个完全自包含的 npm 工程拥有自己的 package.json、next.config.mjs、vitest.config.js可以独立安装、独立测试、独立部署。二、技术栈与依赖根据 docs-site/package.json站点基于以下核心依赖依赖版本以 package.json 为准作用next^16.0.8应用框架与静态站点生成SSGnextra^4.6.1MDX 内容引擎与页面加载nextra-theme-docs^4.6.1文档站主题导航栏、侧边栏、页脚react/react-dom^19.2.1前端运行时vitest^3.2.4dev单元测试next.config.mjs的配置非常精简仅用 Nextra 包装默认配置import nextra from nextra; const withNextra nextra({}); export default withNextra({});而 mdx-components.js 则负责把 Nextra 文档主题的默认 MDX 组件如pre、code、table等与自定义组件合并import { useMDXComponents as getThemeComponents } from nextra-theme-docs; const themeComponents getThemeComponents(); export function useMDXComponents(components) { return { ...themeComponents, ...components, }; }环境要求README 明确指出需要 Node.js 18 与 npm 或 yarn。这与 Next.js 16 的运行时要求一致安装前请先确认node -v满足版本要求。三、安装与内容准备3.1 安装依赖在仓库根目录下进入文档站工程并安装依赖cd docs-site npm install3.2 链接公开文档内容关键步骤文档站的内容并不直接放在站点目录内而是来自父级docs目录。执行npm run link该命令对应 package.json 中的脚本link: node scripts/link-public-docs.mjs实际由 scripts/link-public-docs.mjs 完成。其核心逻辑为删除并重建站点内的content目录复制docs/index.md与docs/_meta.ts作为站点首页与导航元数据遍历公开内容根白名单PUBLIC_DOC_ROOTS将docs下对应子目录以符号链接方式挂到content下。白名单定义在 src/app/public-docs.jsexport const PUBLIC_DOC_ROOTS [users, developers];即只有docs/users用户指南与docs/developers开发者指南会进入公开站点内容树docs/design、docs/plans、docs/e2e-tests等内部规划、设计、E2E 笔记保持在站点内容树之外。3.3 开发服务器npm run dev该脚本先执行npm run clean清理.next构建缓存再以 Turbopack 启动开发服务器dev: npm run clean next --turbopack启动后在浏览器打开http://localhost:3000即可预览文档站。README 中明确给出了该访问地址。四、项目结构与路由机制README 给出了站点目录结构结合仓库源码可进一步还原完整结构docs-site/ ├── scripts/ │ └── link-public-docs.mjs # 内容链接脚本 ├── src/ │ └── app/ │ ├── [[...mdxPath]]/ # MDX 页面动态路由 │ │ ├── page.jsx # 页面组件 静态参数生成 │ │ └── page.test.jsx # 路由过滤测试 │ ├── layout.jsx # 根布局导航栏、横幅、页脚 │ ├── public-docs.js # 公开内容白名单与路径判定 │ └── public-docs.test.js # 白名单逻辑测试 ├── mdx-components.js # MDX 组件配置 ├── next.config.mjs # Next.js 配置 ├── package.json └── vitest.config.js4.1 动态路由[[...mdxPath]]src/app/[[...mdxPath]]/page.jsx 使用 Nextra 提供的generateStaticParamsFor(mdxPath)生成全部静态页面参数并通过filterPublicStaticParams过滤只保留公开路径export const dynamicParams false; export async function generateStaticParams(...args) { const staticParams await generateAllStaticParams(...args); return filterPublicStaticParams(staticParams); }dynamicParams false意味着未在静态参数列表中的路径一律不渲染从构建层面杜绝内部文档被发布。同时页面组件在渲染前还会调用isPublicDocsPath二次校验不通过则notFound()。4.2 公开路径判定逻辑public-docs.js 中的判定函数支持多语言前缀LOCALE_SEGMENTS定义了en、zh、de、fr、ja、ru、pt-BR等语言段路径首个段若是语言代码则跳过再看第二个段是否属于白名单const LOCALE_SEGMENTS new Set([en, zh, de, fr, ja, ru, pt-BR]); const PUBLIC_DOC_ROOT_SET new Set(PUBLIC_DOC_ROOTS); function publicRootFromSegments(segments []) { if (segments.length 0 || (segments.length 1 segments[0] )) { return undefined; } const rootIndex LOCALE_SEGMENTS.has(segments[0]) ? 1 : 0; return segments[rootIndex]; } export function isPublicDocsPath(mdxPath []) { const root publicRootFromSegments(mdxPath); return root undefined || PUBLIC_DOC_ROOT_SET.has(root); }路径判定矩阵由 public-docs.test.js 的用例可直接印证mdxPath是否公开说明[]/[]✅站点首页[users, foo]✅用户指南下任意页面[en, users]✅带语言前缀的公开页[design, bar]❌内部设计文档拒绝发布[plans]❌内部规划文档拒绝发布4.3 失败关闭fails closed设计public-docs.test.js 与 page.test.jsx 都覆盖了一个关键防御场景当 Nextra 未来改变了静态参数的数据结构例如从mdxPath变为slug时过滤逻辑会直接抛出 TypeError 而不是静默放行it(fails closed if Nextra changes the static params shape, () { expect(() filterPublicStaticParams([{ slug: [users] }])).toThrow( Expected generateStaticParamsFor(mdxPath) to return objects with an mdxPath array., ); });这是一种「失败关闭」的安全策略宁可构建失败也不允许内部文档意外流入公开站点。五、根布局与主题配置src/app/layout.jsx 使用nextra-theme-docs提供完整的文档站布局包含横幅、导航栏、侧边栏与页脚const banner ( Banner storageKeysome-keyQwen Code 0.5.0 is released /Banner ); const navbar ( Navbar logo{bQwen Code/b} / ); const footer FooterMIT {new Date().getFullYear()} © Qwen Team./Footer;几个值得注意的配置点pageMap{await getPageMap()}Nextra 根据content目录中的_meta.ts复制自 docs/_meta.ts自动生成导航页图。_meta.ts定义了三个顶层条目隐藏的index首页、usersUser Guide、developersDeveloper Guide侧边栏只会展示这两大公开分区sidebar{{ defaultMenuCollapseLevel: 9999 }}用超大有限整数代替Infinity让所有侧边栏目录默认全部展开注释说明某些 schema 校验器会拒绝Infinitysearch{false}当前关闭了内置搜索docsRepositoryBase指向文档源码仓库的docs目录供「编辑此页」跳转使用HTML 层面设置了langen、dirltr并带suppressHydrationWarning以配合next-themes主题切换。页面渲染时page.jsx 通过importPage(params.mdxPath)加载 MDX 内容、目录toc与元数据并交给主题Wrapper渲染const { default: MDXContent, toc, metadata, sourceCode } await importPage(params.mdxPath); return ( Wrapper toc{toc} metadata{metadata} sourceCode{sourceCode} MDXContent {...props} params{params} / /Wrapper );同时通过generateMetadata将页面 frontmatter 中的 metadata 透出用于 SEO。六、测试体系站点配套了基于 Vitest 的单元测试vitest.config.js 只收集src/**/*.test.{js,jsx}npm test现有两个测试文件覆盖两条核心安全边界public-docs.test.js验证isPublicDocsPath的多语言路径判定矩阵以及filterPublicStaticParams能正确过滤掉design、plans等内部路径、保留users/developers公开路径page.test.jsxmock 掉nextra/pages后验证generateStaticParams在构建期同样只产出公开路径并验证失败关闭行为。七、从 README 到生产部署实操要点总结把 docs-site/README.md 的操作步骤串联成一条可复用的完整流程# 1. 安装依赖Node.js 18 cd docs-site npm install # 2. 准备公开内容生成 content/ 目录 npm run link # 3. 本地开发预览http://localhost:3000 npm run dev # 4. 运行安全边界测试 npm test几个实际使用中的要点每次内容变更后需重新执行npm run link因为content目录每次都会被重建rmmkdir 重新cp/symlink新建的公开文档才会被纳入站点新增公开分区需要同步改两处一是 docs/_meta.ts 增加顶层条目二是 docs-site/src/app/public-docs.js 的PUBLIC_DOC_ROOTS加入对应目录名源码注释明确要求两者保持同步且 scripts/link-public-docs.mjs 消费同一个白名单内部文档天然隔离docs/design、docs/plans、docs/e2e-tests等目录既不会被链接进content又会被静态路由过滤拒绝形成双重保险部署形态next.config.mjs未做任何自定义输出配置直接使用 Next.js 默认构建即可产出可部署的静态站点产物next build适合托管到各类静态站点平台。八、总结Qwen Code 的 docs-site 展示了一种干净利落的「单仓库双内容域」文档站组织方式用独立 Next.js 工程承载站点骨架用符号链接按需挂载公开文档再用「构建期静态参数过滤 运行期路径判定 失败关闭测试」三重机制守住内部内容不外泄的边界。无论你是想为开源项目搭建官方文档站还是需要在巨型 monorepo 中隔离公开与内部文档这套基于 Next.js 16 Nextra 4 的方案都值得直接参考与复用。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考