Skip to content

ci: add docs pages workflow - #31

Merged
Radiant303 merged 1 commit into
Radiant303:mainfrom
lxfight:ci/docs-pages-workflow
Jun 26, 2026
Merged

Radiant303 merged 1 commit into
Radiant303:mainfrom
lxfight:ci/docs-pages-workflow

Conversation

@lxfight

@lxfight lxfight commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

概述 / Summary

为 VitePress 文档站点新增 GitHub Actions 自动构建与 GitHub Pages 部署流程。PR 会在文档相关变更时校验 docs 构建,合并到主分支后自动发布页面。

改动点 / Changes

  • 新增 .github/workflows/docs.yml,在 PR 中执行 npm ci 与 npm run build。
  • 主分支 push 时上传 VitePress 构建产物并通过 GitHub Pages 部署。
  • 为 VitePress 增加 DOCS_BASE 配置,适配 GitHub Pages 项目路径 /SpringNote/。
  • 将首页手写文档入口改为相对链接,避免 Pages 子路径部署后跳出站点路径。

截图或录屏 / Screenshots or Recordings

不涉及页面视觉改动。

验证方式 / Verification

  • flutter analyze
  • flutter test
  • cargo test in spring_note/rust
  • flutter build windows --release
  • 手动测试 / Manual test:npm run build in docs
  • 手动测试 / Manual test:DOCS_BASE=/SpringNote/ npm run build in docs

检查清单 / Checklist

  • 😊 本 PR 范围清晰,不包含无关改动。/ This PR has a clear scope and does not include unrelated changes.
  • 👀 我已测试受影响功能,或说明了为什么不适用测试。/ I have tested the affected feature or explained why testing is not applicable.
  • 🖼️ 如果修改了 UI,我已附上截图或录屏。/ If this changes UI, I have attached screenshots or recordings.
  • 🤓 如果修改了依赖,我已更新 pubspec.yaml、pubspec.lock、Cargo.toml 或 Cargo.lock 等对应文件。/ If this changes dependencies, I have updated the correct files such as pubspec.yaml, pubspec.lock, Cargo.toml, or Cargo.lock.
  • 🔐 本 PR 没有暴露 API Key、Token、本地路径或用户隐私数据。/ This PR does not expose API keys, tokens, local paths, or private user data.
  • 😮 本 PR 没有引入恶意代码。/ This PR does not introduce malicious code.

破坏性变更 / Breaking changes

  • 这不是破坏性变更。/ This is NOT a breaking change.
  • 这是破坏性变更,我已在下方说明影响。/ This is a breaking change and I have explained the impact below.

@github-actions

Copy link
Copy Markdown
Contributor

AI 审查结果

审查结论

本次 PR 整体质量良好,主要目的是为文档站点添加 GitHub Pages 部署 CI/CD,并调整文档配置以支持子路径部署。未发现严重 bug、安全漏洞或性能问题。但存在几处低严重度的潜在风险与可维护性改进点,建议在合并前修复。


问题列表

1. 低严重度:DOCS_BASE 环境变量尾部斜杠依赖可能导致 favicon 路径错误

  • 位置:docs/.vitepress/config.mts 第 12 行
  • 原因:favicon 的 href 通过模板字符串 ${process.env.DOCS_BASE || '/'}images/logo.png 拼接。若 DOCS_BASE 被设置为不带尾部斜杠的值(例如 /SpringNote),则拼接结果为 /SpringNoteimages/logo.png,导致 404。当前 workflow 中 DOCS_BASE 值(/ 或 /SpringNote/)均以斜杠结尾,但其他构建方式(如本地开发、其他 CI 环境)可能忽略此约定。
  • 建议修复:在 config.mts 中对 DOCS_BASE 进行规范化,确保以斜杠结尾。例如:
    const base = (process.env.DOCS_BASE || '/').replace(/\/?$/, '/');
    export default defineConfig({
      base,
      head: [
        ['link', { rel: 'icon', href: `${base}images/logo.png` }],
        // ...
      ],
    });

2. 低严重度:favicon 路径未统一使用 base 变量,可维护性不足

  • 位置:docs/.vitepress/config.mts 第 12 行
  • 原因:base 配置项与 head 中的 favicon 路径分别引用了 process.env.DOCS_BASE,未提取为共享常量。未来若新增其他依赖 base 的路径(如其他 <link> 或 <meta>),容易遗漏或产生不一致。
  • 建议修复:将 base 值提取为常量(如上述修复所示),并在所有需要的地方引用该常量,避免重复计算和潜在不一致。

3. 低严重度:相对路径链接在文档结构变动时可能失效

  • 位置:docs/en/index.md 第 16 行、docs/index.md 第 16 行
  • 原因:将绝对路径 /en/features 和 /features 改为相对路径 ./features。当前行为正确(英文版解析为 /en/features,中文版解析为 /features),但若未来调整目录结构(例如将 index.md 移入子目录),相对路径将指向错误位置。
  • 建议修复:当前修改是支持子路径部署的必要改进,无需回退。但建议在文档重构时注意保持相对路径与页面位置的对应关系,或考虑使用 VitePress 的 $withBase 辅助函数(但 markdown 中无法直接使用)。可接受当前方案。

4. 信息:缺少对构建产物的链接有效性验证

  • 位置:整个 PR(.github/workflows/docs.yml)
  • 原因:工作流仅执行构建和部署,未添加步骤验证生成的 HTML 中链接是否正确(例如 favicon、内部导航等)。虽然当前修改经过人工审查,但自动化验证可防止未来引入死链。
  • 建议修复:在 build 步骤后添加一个检查步骤,例如使用 htmlproofer 或 broken-link-checker 扫描 docs/.vitepress/dist 目录。可参考:
    - name: Check links
      run: npx htmlproofer docs/.vitepress/dist --check-html --disable-external

剩余风险

  • workflow 依赖 docs/package-lock.json 存在:npm ci 要求该文件存在,若缺失则构建失败。此风险不在 diff 范围内,但需确保项目根目录下 docs/ 子目录包含有效的 package-lock.json。
  • PR 构建产物 base 与部署 base 不同:PR 触发时 DOCS_BASE 设为 /,而部署时设为 /SpringNote/。由于 PR 构建不部署,不影响线上站点;但若未来添加 PR 预览部署功能,需同步调整 base 逻辑。
  • 仓库重命名风险:workflow 中硬编码了仓库名 SpringNote,若仓库改名需同步更新 DOCS_BASE 值。建议考虑使用 ${{ github.event.repository.name }} 动态获取,但当前硬编码可接受。

@lxfight

lxfight commented Jun 26, 2026

Copy link
Copy Markdown
Contributor Author

@Radiant303

@Radiant303

Copy link
Copy Markdown
Owner

@Radiant303

妙啊妙啊

@Radiant303
Radiant303 merged commit f6dddb5 into Radiant303:main Jun 26, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants