GitHub Pages 部署

文档站位于：

docs-site/

它使用：

• Bun 作为 package manager 和 script runner
• Nextra 作为文档主题
• Next static export 生成静态文件
• GitHub Actions 部署到 GitHub Pages

本地命令

安装依赖：

cd docs-site
bun install

启动开发服务器：

bun run dev

构建静态站点：

bun run build

构建输出目录：

docs-site/out/

Base path

GitHub project Pages 通常部署在：

https://<owner>.github.io/<repo>/

因此 workflow 里运行 build 时，next.config.mjs 会检测 GITHUB_ACTIONS=true，并把 basePath 设置为仓库名：

/LightFlow

本地开发时不设置 base path，仍然使用：

http://localhost:3000/

GitHub 设置

首次启用 Pages 时，在 GitHub 仓库里设置：

1. 打开 Settings。
2. 进入 Pages。
3. 在 Build and deployment 中选择 Source: GitHub Actions。
4. 推送到 main 或手动运行 workflow。

Workflow 文件

部署 workflow 位于：

.github/workflows/docs-pages.yml

它会在 push 到 main 时运行，也支持手动触发。

常见问题

如果页面 CSS 或 JS 404，通常是 base path 不匹配。确认仓库名是否仍为 LightFlow，以及 Pages URL 是否是 project Pages。

如果 Pages 部署成功但页面空白，先在 Actions 日志里确认 docs-site/out/ 已上传，再检查浏览器 network 面板里的 _next/static 路径。

如果 bun install --frozen-lockfile 失败，说明 docs-site/package.json 和 docs-site/bun.lock 不一致。本地重新执行 bun install 并提交 lockfile。