wigolo 官网站点架构解析基于 Next.js 静态导出构建 GitHub Pages 落地页与文档站【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo本文档讲解 wigolo 开源仓库中site/子目录的完整技术实现——一个用于项目官方落地页与文档站的 Next.js 静态站点。你将掌握它的本地开发流程、GitHub Pages 静态导出的核心配置、base path 环境变量的作用原理、构建期文档管线以及 SEO 元数据处理方式从而能够在自己的开源项目中复刻这套单仓库 子目录站点 Pages 部署的方案。一、站点定位一个仓库内嵌的静态站点site/目录承载的是 wigolo 的官方 landing site它和主项目源码放在同一个仓库内是一个独立的 Next.js 应用。其最大特点是完全静态化所有页面在构建期生成产物可直接部署到 GitHub Pages不需要任何运行时服务。README 明确说明站点由.github/workflows/site.yml工作流负责部署当site/目录下的文件被推送到main分支时触发构建与发布。从目录结构看站点由三部分构成页面与组件入口页 site/src/app/page.tsx 按顺序组合 Hero、FeatureMarquee、Stats、HowItWorks、TrustedBy、Tools、OpenSource、Testimonials、Parity、StartShipping、Quickstart、Feedback 等 14 个区块组件文档站/docs路由site/src/app/docs/[slug]/page.tsx在构建期直接读取仓库根目录的docs/下的 Markdown 文件渲染成文档页面公共资源站点用到的图标、社交分享图、演示视频等静态资源集中在 site/public/ 下。依赖方面站点使用 Next.js 16.2.10 React 19.2.4并引入react-markdown配合remark-gfm、rehype-slug、rehype-highlight做文档渲染、motion做动效、highlight.js做代码高亮具体见 site/package.json。二、本地开发三条命令跑通全流程site/README.md给出了最简可用的开发流程原文三行命令对应三个不同阶段npm ci npm run dev # local dev at localhost:3000 (no base path) npm run build # static export to out/npm ci按package-lock.json锁定版本安装依赖保证 CI 与本地环境一致npm run dev启动开发服务器默认监听localhost:3000。此时NEXT_PUBLIC_BASE_PATH未设置所有资源从根路径/提供方便快速预览npm run build执行生产构建产物输出到out/目录这是后面要讲的静态导出模式。此外 site/package.json 还提供了npm run start本地预览生产构建结果和npm run lintESLint 检查配置文件为 site/eslint.config.mjs。三、静态导出核心配置next.config.ts 逐项拆解站点能否零服务器部署关键在 site/next.config.ts 这份配置文件。它只有十几行但每一行都服务于 GitHub Pages 部署这一目标const basePath process.env.NEXT_PUBLIC_BASE_PATH ?? ; const nextConfig: NextConfig { output: export, basePath: basePath || undefined, images: { unoptimized: true }, trailingSlash: true, turbopack: { root: __dirname, }, };逐项说明其作用与原因output: export启用 Next.js 静态导出模式。构建时把整站预渲染为纯 HTML/CSS/JS产物落在out/无需 Node 服务即可托管。这也是npm run build能产出静态文件、Pages 能直接托管的根本原因basePath: basePath || undefinedGitHub Pages 项目页project pages的站点不是挂在域名根路径而是挂在仓库子路径如/wigolo下。basePath会把所有路由与资源引用统一加上该前缀。本地开发时环境变量为空basePath退化为undefined一切照常从/提供images: { unoptimized: true }关闭 Next 内置图片优化。Pages 是纯静态托管没有图片优化服务端此配置确保next/image直接输出原图而不是运行时优化trailingSlash: true为所有路由生成带尾部斜杠的 URL/docs/而非/docs与 Pages 静态文件的目录式托管语义保持一致避免刷新时 404turbopack: { root: __dirname }显式指定 Turbopack 的根目录为站点目录本身保证模块解析边界正确站点是仓库的子目录。四、环境变量三条 Pages 部署关键变量site/README.md用一张表定义了三个环境变量它们由 Pages 工作流注入本地开发时可留空变量作用NEXT_PUBLIC_BASE_PATHGitHub Pages 项目托管下为/wigolo本地不设置NEXT_PUBLIC_SITE_URL元数据 / OG 分享图的 Canonical URLhttps://knockoutez.github.io/wigoloNEXT_PUBLIC_WEB3FORMS_KEY快速反馈表单的访问密钥web3forms.com。未设置时表单隐藏只显示 GitHub 链接三者各有对应源码实现理解它们能帮你判断何时该设置、何时可忽略1.NEXT_PUBLIC_BASE_PATH——资源与路由的前缀开关。在 site/src/lib/site.ts 中定义export const BASE_PATH process.env.NEXT_PUBLIC_BASE_PATH ?? ; export const asset (path: string) ${BASE_PATH}${path};所有/public下的资源引用都必须经asset()包裹从而在 base path 模式下自动补前缀、本地模式下原样输出。以导航栏为例site/src/components/Nav.tsxlogo 图片用asset(/wigolo/wigolo-icon.png)首页链接用${BASE_PATH}/Docs 链接用${BASE_PATH}/docs——同一个组件在两种环境下都能正确指向资源与路由。2.NEXT_PUBLIC_SITE_URL——Canonical 与 OG 的域名基准。site/src/app/layout.tsx 中export const SITE_URL process.env.NEXT_PUBLIC_SITE_URL ?? http://localhost:3000;它被用作metadataBaseNext.js 会据此把相对路径的元数据 URLcanonical、OG 图片等拼成绝对地址。注意 site/src/lib/site.ts 中默认值写的是http://localhost:3000而 README 给出的线上值由工作流注入——这正是工作流注入、本地可选的设计。3.NEXT_PUBLIC_WEB3FORMS_KEY——反馈表单的降级开关。反馈区块site/src/components/Feedback.tsx中const WEB3FORMS_KEY process.env.NEXT_PUBLIC_WEB3FORMS_KEY; if (!WEB3FORMS_KEY) return null;密钥未设置时整个QuickForm组件渲染为空页面上只保留Report a bug / Request a feature / Ask a question三个 GitHub 链接。设置了密钥后表单会把内容 POST 到 web3forms 的提交接口并附带一个隐藏的botcheck蜜罐字段防机器人。这种环境变量驱动 UI 降级的做法保证了没有第三方服务密钥时站点依然完整可用。五、SEO 与结构化数据元数据集中在根布局SEO 信息没有散落在各页面而是统一收敛在根布局 site/src/app/layout.tsx 中包含四层基础 metadatatitle含%s · wigolo模板、description、keywords、authors、robots允许索引并开启大图预览Open Graph / Twitterog:type: website、分享图指向/wigolo/wigolo-social.png对应 site/public/wigolo/wigolo-social.png尺寸 1200×630 符合社交分享规范。注意源码注释特意提醒OG 图片用普通公共路径而非asset()因为metadataBase已携带 base path再用asset()会重复加前缀JSON-LD 结构化数据内嵌SoftwareApplication类型脚本声明名称、分类、操作系统、版本0.2.x public beta、许可证、价格0 USD等字段便于搜索引擎和 LLM 理解项目性质canonical/docs/[slug]文档页在 site/src/app/docs/[slug]/page.tsx 中通过generateMetadata单独设置canonical: /docs/${slug}。六、构建期文档管线docs.ts 的静态化魔法站点最有技术含量的部分是文档站管线核心实现在 site/src/lib/docs.ts。它的设计思路是公开文档以 Markdown 形式存放在仓库根目录的docs/中仓库文档与站点文档同源构建时由文件系统读取并渲染进静态导出运行时零请求。几个关键机制读取路径DOCS_DIR join(process.cwd(), .., docs)即site/的上一级目录。因为静态导出在next build阶段执行 Server Component所以构建时用fs读文件完全可行渲染后的 HTML 直接进入产物导航清单DOCS_NAV按序定义 13 个文档页Overview 到 Privacy security同时充当侧边栏顺序、路由生成源generateStaticParams和前一篇/后一篇导航getDocNeighbours的数据源链接重写rewriteHref把文档内./other.md、./other.md#anchor形式的相对链接重写为/docs/other站点路由把跳出docs/的../xxx链接解析为仓库内文件实现了一份 Markdown、仓库与站点双端可用构建期同步校验assertDocsInSync在构建时对比docs/磁盘上的 Markdown 文件与DOCS_NAV若新增/删除文件而未更新导航直接抛错让构建失败——用宁可失败也不静默丢页的方式保证导航与文档永远一致。渲染链路为react-markdownremark-gfmGFM 表格支持rehype-slug标题锚点rehype-highlight代码高亮配合highlight.js主题最终在 site/src/components/docs/ 的 DocShell 中呈现带侧边栏与正文的文档布局。七、字体自托管与公共资源组织site/README.md特别说明站点字体为开放许可构建期通过next/font自托管包括 Bricolage Grotesque展示字体、Instrument Sans正文、Azeret Mono等宽三种。在 site/src/app/layout.tsx 中可以看到它们的加载方式const display Bricolage_Grotesque({ subsets: [latin], weight: [400, 500, 700], variable: --font-display }); const body Instrument_Sans({ subsets: [latin], weight: [400, 500], variable: --font-body }); const mono Azeret_Mono({ subsets: [latin], weight: [400, 500, 700], variable: --font-mono });字体通过 CSS 变量--font-display/--font-body/--font-mono注入html的 class供全站样式消费。next/font在构建期把字体文件下载并内嵌到产物中不依赖 Google Fonts 的运行时 CDN——这保证了静态站点在 Pages 上永远能渲染出目标字体也避免了外部请求。公共资源方面site/public/ 按wigolo/与promo/两个目录组织前者放图标、社交分享图、品牌字标和演示视频后者放各个宣传 SVG 动图。所有引用都走asset()以保证 base path 兼容。八、部署到 GitHub Pages工作流要点虽然.github/workflows/site.yml本身不在site/内但 README 明确了部署模型推送到main且改动触及site/时工作流执行npm ci npm run build把out/产物发布到 GitHub Pages 项目托管同时注入前面三个NEXT_PUBLIC_*环境变量BASE_PATH/wigolo、SITE_URLhttps://knockoutez.github.io/wigolo、WEB3FORMS_KEY取仓库 secrets。从源码可以验证这套部署假设为何成立output: export保证out/是纯静态文件trailingSlash保证目录式托管下链接可直达images.unoptimized消除运行时图片优化依赖asset()与BASE_PATH贯穿全站资源引用确保子路径托管下不出现 404。如果你要在自己的开源项目中复用这套方案需要同时满足三个条件静态导出配置output、basePath、unoptimized 图片、所有公共资源经统一的 asset 助手函数处理、环境变量由 CI 按环境注入。九、小结site/目录展示了开源项目常见的仓库内嵌官方站点模式以 site/next.config.ts 的静态导出为核心以NEXT_PUBLIC_BASE_PATH、NEXT_PUBLIC_SITE_URL、NEXT_PUBLIC_WEB3FORMS_KEY三个环境变量应对本地/线上、有无第三方密钥的不同环境以 site/src/lib/site.ts 的asset()统一资源前缀以 site/src/lib/docs.ts 的构建期文档管线实现仓库 docs 即站点文档。这套组合让官网页面、文档站、SEO 元数据与反馈入口全部静态化仅凭 GitHub Pages 即可零成本、零服务器地长期运行——这也是 wigolo 坚持 local-first、无云依赖理念在官方站点侧的一致体现。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考