refactor(site): migrate from Valaxy to VitePress

[AdingApkgg]

Description / 描述

将文档站从 Valaxy 迁移到 VitePress，并把工具链升级到最新稳定版。

	迁移前	迁移后
框架	Valaxy 0.25.9 + valaxy-theme-press（含 2 个 patch）	VitePress 1.6.4
包管理器	pnpm 10	pnpm 12.6.0
Node（CI）	22	24 LTS
搜索	Algolia	Algolia（不变）
首页	valaxy-theme-press 自定义首页	还原旧版首页并加入流光效果（HomeHero.vue）
格式化 / Lint	Prettier	Prettier（格式化）+ ESLint 10（typescript-eslint、eslint-plugin-vue，含 Vue 模板检查）
CI	仅构建部署	新增 ci.yml：所有 PR 和 main 推送都会运行 format:check + lint + typecheck

页面结构

• 中英文混写的单文件拆成每种语言一个文件：中文在 pages/（站点根路径），英文在 pages/en/（/en/）。
• 拆分用 markdown-it 自身的解析完成，并逐文件把拆分结果与原文的 token 结构做比对。
• 页面标题从 frontmatter 的 title 改为正文第一行的 # 标题；侧边栏仍由 categories / top 生成，顺序与现网一致。

功能

• 保留：贡献者列表、giscus 评论（中英文共用同一讨论，与原来一致）、最后更新时间、编辑链接、页脚/ICP、B 站视频、下载组件、浅色/深色图片、代码组图标。
• mermaid：自带组件支持 mermaid 12（社区插件只支持到 11）。
• 语言跳转：首次访问按浏览器语言跳转；沿用旧站保存的语言偏好（valaxy-lang）；之后记住用户最后使用的语言。爬虫不会被跳转。
• 首页：还原旧站首页（浮动 logo、渐变标题、「快速上手」按钮悬停时文字飞走 logo 飞入），并加入流光效果：
  • 标题中持续流过的光带；
  • logo 背后和主按钮边框上旋转的光环；
  • 缓慢漂移的极光背景。
  • 浅色 / 深色模式和手机宽度都已适配；系统开启「减少动态效果」时关闭动画。
• 搜索：继续使用 Algolia，配置与原来一致。
• 主题：默认跟随系统，外观切换改为「跟随系统 / 浅色 / 深色」三态（原来只有浅色 / 深色两态，点过之后没法明确回到跟随系统）。桌面导航栏、「…」菜单和手机菜单都已替换。
• 导航栏：修复 768–959px 宽度下导航栏横向溢出（最多 126px），这个区间内搜索框只显示图标。

顺带修复的内容问题

有 8 个页面的 ::: 容器嵌套写错，导致现网内容显示不正确：

• 115 开放平台的英文「Notes」一节，英文页面上看不到。
• 189 的中文提示，中文页面上看不到。
• Worker 的 Troubleshooting 中英文互相串，还有几处 ::: 直接显示成文字。

另外 worker 首页的 ./architecture、./faq 本来就是死链，已改为指向 ./basic、./about。

Review 建议

约 740 个文件的改动大部分是机械拆分和目录移动。需要重点看的是 .vitepress/ 下的配置与主题、package.json、CI workflow，以及上面提到的 8 个内容修复。

Motivation and Context / 背景

• Valaxy 已落后 14 个月（最新为 1.0.0-rc.15），并且依赖两个 patch。

• 中英文写在同一页里：HTML 固定为 lang="en"、标题只有英文、没有 hreflang，对 SEO 和搜索都不友好。

• 构建耗时和内存：

  	Valaxy	VitePress
  构建耗时	约 5.8 分钟	约 20–45 秒（随机器负载变化）
  峰值内存	2.8 GB	1.8 GB
  CPU 用户时间	147 秒	约 32 秒

• 旧站在 Node 25 上生成页面时会出错（devtools-kit 的 localStorage 问题），但构建仍然返回成功，只产出 2 个 HTML。

• 项目用户以国内为主，因此中文放在根路径。

测试

• pnpm build 通过：共 288 个页面，死链检查全部通过。
• 另外用 Node 25、Node 26，以及 GitHub Pages 子路径（VITE_BASE）分别构建，均成功。
• pnpm format:check（Prettier）、pnpm lint（ESLint）、pnpm typecheck（vue-tsc + TypeScript 6.0.3）通过。
• 侧边栏：中英文两套都与现网逐项比对，141 项的顺序完全一致。
• 浏览器实测：首页（浅色 / 深色 / 手机宽度 / 悬停效果）、中英文页面、mermaid、浅色/深色图片、下载组件、贡献者、giscus、4 种语言跳转情况、Algolia 搜索框，控制台没有报错。

合并后需要在仓库外处理

• Algolia 爬虫：上线后需要尽快重新爬取并检查配置。
  • 现有索引的记录都标记为 lang: en，而且指向根路径；迁移后根路径是中文页面，英文页面在 /en/。
  • VitePress 按页面语言过滤搜索结果（中文为 lang:zh-CN，英文为 lang:en）。重新爬取之前，中文搜索没有结果，英文搜索会跳到中文页面。
• Cloudflare Pages / 国内镜像：确认构建环境的 pnpm 支持 12.x。通过 Corepack 使用 pnpm 时需要 Corepack 0.35 及以上（Node 24.21 自带 0.36）；构建命令 pnpm build，输出目录仍为 dist。

Checklist / 检查清单

• I have read the CONTRIBUTING document.
  我已阅读 CONTRIBUTING 文档。（本 PR 同时更新了该文档）
• I have formatted my code or documentation with prettier or other appropriate formatter.
  我已使用 prettier 或其他适当的格式化工具格式化提交的代码或文档。
• I have updated all supported languages (including Chinese and English) for documentation. (If it's needed)
  我已为所有支持语言（包括中文和英文）更新文档内容。 (若适用)
• I have verified that the written documentation or code is properly formatted, with no syntax errors, spelling mistakes.
  我已确认编写的文档或代码格式正确, 无语法错误, 拼写错误。
• I have updated the repository accordingly (If it's needed).
  我已相应更新了相关仓库（若适用）。（不适用）

🤖 Generated with Claude Code

[xrgzs]

1. 首页建议重构一下，不要用 VitePress 默认的
2. 包管理器换回 pnpm，符合开发习惯
3. 搜索继续使用Algolia

[AdingApkgg]

@xrgzs 感谢 review，三点都已处理：

1. 首页：已还原旧站首页（浮动 logo、渐变标题、「快速上手」悬停时文字飞走 logo 飞入），并在此基础上加入了流光效果（标题流光、logo 与主按钮的旋转光环、背景光晕），配色沿用旧站品牌色。浅色 / 深色 / 手机宽度都已适配，系统开启「减少动态效果」时自动关闭动画。实现在 .vitepress/theme/components/HomeHero.vue（9877d6d、9a4a1df）。
2. 包管理器：已换回 pnpm（12.6.0）。CI 使用 pnpm/setup@v3，由它安装 pnpm 和 Node.js 并执行 pnpm install --frozen-lockfile（9877d6d）。
3. 搜索：已恢复 Algolia，配置与原来一致，algolia-verify.html 也已恢复（9877d6d）。
   需要注意：迁移后中文在根路径、英文在 /en/，而现有索引的记录都标记为 lang: en 且指向根路径。上线后需要尽快让爬虫重新爬取一次，否则中文搜索没有结果，英文搜索会跳到中文页面。

另外顺带做了两处改动：

• 主题切换改为「跟随系统 / 浅色 / 深色」三态（c27172b）。
• 修复了 768–959px 宽度下导航栏横向溢出的问题（f6b9471）。

🤖 Generated with Claude Code

[ILoveScratch2]

1. 目前我们并没有迁移到 VitePress 的规划，此类重大迁移应提前协商沟通而非直接提交，仍有待讨论
2. ecosystem paas 等页面引入了问题
3. 部分中文页面没有完全修复，也没有完全同步英文
4. 该 PR 体量过大，应拆分为多个修复，否则不利于历史回溯，也不便于审查代码

[AdingApkgg]

@ILoveScratch2 感谢 review，逐条回复：

1. 迁移规划

迁移之前我和 @cxw620 沟通过（2025 年 6 月）。当时我提的是用 Zola，他指出 Zola 的 i18n 和中文搜索有问题，而现有文档大量依赖 Vue，建议如果要换框架就一步到位用 VitePress，并没有反对。这个 PR 就是按这个方向做的。当然欢迎大家继续讨论，有顾虑可以直接在这里提。

2. ecosystem、paas 的问题：已在 e9e305c 修复。

• ecosystem：英文页缺少 jiwangyihao/olist-cdn-preheat 这一条（原文 HisAtri 的中文块没有闭合，把它吞了进去，现网的英文页同样看不到）；OpenList Docs 的描述改为 VitePress；补齐了缺失的 --- 分隔线。
• paas：页尾注释里残留的旧双语写法已按语言拆开。

3. 中文页面与英文不同步

我在迁移前的原文里全面查了「某种语言的内容被嵌进另一种语言块」的问题，共 9 处，都已修复：115、115_open、189、thunder、reverse-proxy、ecosystem、desktop、worker、official_worker/guide、seeds/design。

仍有少量中英文不一致是原文本来就存在的，不是迁移引入的：

• 只有一种语言有的内容：google_photos、thunder（Use video url 一节）、global、Authentik、preview，以及 115 中只有中文才有的视频教程和截图。
• 只是标题层级不同：other、preview、guide_env、baidu、ftp、mediatrack、mopan、teambition、uss。

如果需要，我可以单独提 PR 补齐。

4. PR 体量

内容修复已经拆出来，按现在的 Valaxy 写法单独提交为 #380，不依赖迁移，可以先合并，直接修复现网。

#377 剩下的主要是：

• 按语言拆分页面：由脚本生成，并逐文件和原文的解析结构做了比对；
• VitePress 配置与主题；
• 工具链与 CI。

提交也基本按主题分开。如果维护者更希望拆成多个 PR（比如把工具链和 CI 放到迁移之后再单独提），我可以再拆。

🤖 Generated with Claude Code