From 4dc31670faaf2ca46da95b5fcd0b7a04834a4093 Mon Sep 17 00:00:00 2001 From: 100gle Date: Wed, 12 Aug 2026 21:17:13 +0800 Subject: [PATCH] docs(website): document Astro 7 migration plan --- website/STARLIGHT_ASTRO7_RESEARCH.md | 303 +++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 website/STARLIGHT_ASTRO7_RESEARCH.md diff --git a/website/STARLIGHT_ASTRO7_RESEARCH.md b/website/STARLIGHT_ASTRO7_RESEARCH.md new file mode 100644 index 00000000..8c66e6ce --- /dev/null +++ b/website/STARLIGHT_ASTRO7_RESEARCH.md @@ -0,0 +1,303 @@ +# Starlight 统一与 Astro 7 升级调研 + +> 调研日期：2026-08-12 +> 仓库基线：`9c0da67`，`website/package.json` 使用 Astro 6.1.10 +> 范围：只评估 `website/`；未修改站点实现。升级验证在 `/tmp` 隔离副本中完成。 + +## 结论 + +1. **不能用 Starlight 替换 Astro。** Starlight 是运行在 Astro 中的文档站框架/集成；一个 Starlight 项目仍然需要 `astro`、`astro.config.mjs`、Astro 路由和 Astro 构建。当前仓库其实已经是“同一 Astro 站点内，docs 使用 Starlight，landing/blog 使用 Astro 自定义页面”的官方支持形态。[Starlight 手工安装](https://starlight.astro.build/manual-setup/)和[项目结构](https://starlight.astro.build/guides/project-structure/)都把 Starlight 定义为 Astro 集成。 +2. **docs 与 blog 可以统一外观、Markdown 处理和搜索入口，但不能因此删掉 Astro。** 最稳的方式是保留独立 `posts` collection 和现有 URL，只让 Blog 页面改用 ``；把 Blog 强行移进 Starlight 的 `docs` collection 也能做，但日期、标签、列表、文章元数据和 OG 图仍要自己实现，复杂度只是换了位置。 +3. **建议先单独升级 Astro 7，再决定是否统一 Blog UI。** 依赖升级和页面重构不要放在同一个变更中。Astro 7 已于 2026-06-22 正式发布；截至本次调研，npm 最新稳定版为 7.2.1。[Astro 7 发布说明](https://astro.build/blog/astro-7/)、[v7 迁移指南](https://docs.astro.build/en/guides/upgrade-to/v7/) +4. **本仓库升级 Astro 7 的风险为低到中。** 隔离副本在完成本文列出的依赖与 sidebar 改动后，生产构建通过，Mermaid 由 Sätteri 正常转换，Wrangler 本地预览的首页、英文 docs、英文 post、中文 docs 均返回 200。尚需正式变更中的视觉回归和真实 Cloudflare 部署验证。 + +推荐决策： + +- 现在执行“Astro 7 工具链升级”。 +- 保留现有三类页面边界，不把 Blog 内容迁入 `docs` collection。 +- 如果目标是统一 Header、主题、正文样式和全文搜索，升级完成后再单独做“Blog 使用 ``”的小型重构。 + +## 当前站点基线 + +当前实现已经同时使用 Astro 和 Starlight： + +- 34 篇英文 docs + 34 篇中文 docs：由 Starlight `docsLoader()`/`docsSchema()` 自动生成。 +- 3 篇英文 post + 3 篇中文 post：独立 `posts` collection，由 Astro 动态路由生成。 +- Landing、404、Blog list、Blog article：自定义 Astro 页面和布局。 +- 英文为根路径，中文使用 `/zh-cn/`；docs 和自定义页面目前使用两套 i18n 入口。 +- Landing 为按需渲染；docs 与 Blog 文章为预渲染；最终由 Cloudflare Workers adapter 输出。 + +关键文件： + +- [`package.json`](./package.json) +- [`astro.config.mjs`](./astro.config.mjs) +- [`src/content.config.ts`](./src/content.config.ts) +- [`src/pages/[...locale]/posts/[slug].astro`](./src/pages/%5B...locale%5D/posts/%5Bslug%5D.astro) +- [`src/layouts/PostLayout.astro`](./src/layouts/PostLayout.astro) +- [`src/layouts/BaseLayout.astro`](./src/layouts/BaseLayout.astro) + +当前版本： + +| 包 | 当前版本/约束 | 现状 | +|---|---:|---| +| `astro` | `^6.1.10` | Astro 6 | +| `@astrojs/starlight` | `^0.38.3` | 只支持 Astro 6 | +| `@astrojs/cloudflare` | `^13.1.9`，lock 为 13.1.10 | Astro 6 adapter | +| `astro-mermaid` | `^2.0.1`，lock 为 2.0.1 | 使用旧 remark/rehype 注入方式 | +| `@tailwindcss/vite` | `^4.1.14`，lock 为 4.2.2 | 已支持 Vite 8，无需改动 | +| `@lucide/astro` | `^1.8.0`，lock 为 1.8.0 | peer range 不含 Astro 7 | +| `wrangler` | `^4.13.2`，lock 为 4.83.0 | 低于新 Cloudflare Vite plugin 要求 | +| `vite` override | `^7.3.2` | 会阻止 Astro 7 使用 Vite 8 | + +还有两个与“统一”直接相关的现状： + +- 当前构建生成 77 个 HTML 文件，Pagefind 能发现 77 个，但因为 Starlight 页面带有 `data-pagefind-body`，Pagefind 会忽略没有该标记的自定义页面，最终只索引 68 个 docs 页面；现有 6 篇 Blog 文章和 2 个 Blog list 没有进入搜索索引。这是本地用 Pagefind verbose 模式复核的结果。 +- Blog list 显式传入 canonical URL，但当前 Blog article 的 `PostLayout` 没有向 `BaseLayout` 传 canonical，也没有生成英中 hreflang。使用 `StarlightPage` 后可复用 Starlight 的 canonical/hreflang 生成，但仍要合并现有动态 OG image。 + +## 调研一：能否直接使用 Starlight 统一 docs 与 blog + +### 能统一什么，不能统一什么 + +| 层面 | 是否可统一 | 说明 | +|---|---|---| +| 构建框架 | 否 | Starlight 依赖 Astro，不能替代 `astro`。 | +| Header、主题、响应式布局 | 是 | 自定义 Astro 页面可用 `` 渲染完整 Starlight 页面。[官方 custom pages 指南](https://starlight.astro.build/guides/pages/#custom-pages) | +| Markdown 处理 | 是 | 独立 collection 可通过 `markdown.processedDirs` 使用 Starlight 的 heading、aside、代码块等处理。[配置参考](https://starlight.astro.build/reference/configuration/#processeddirs) | +| 全文搜索 | 是，但页面必须采用 Starlight 页面结构或自行标记 | `` 最终使用 Starlight `Page.astro`，会加入 Pagefind body 标记。[Starlight Page 源码](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Page.astro) | +| Blog 日期、标签、归档、列表、RSS | 否，需自建 | Starlight 核心面向 docs，不提供完整 Blog domain model。官方资源页把 `starlight-blog` 列为社区插件，而不是官方插件。[插件目录](https://starlight.astro.build/resources/plugins/) | +| 多语言内容 fallback | docs collection 可自动；自定义 Blog 不自动 | Starlight 通过同路径内容文件关联翻译并提供 fallback；独立 custom routes 仍需当前 i18n 逻辑。[i18n 指南](https://starlight.astro.build/guides/i18n/) | +| Astro 自定义页面/路由 | 仍然需要 | Starlight 官方明确支持同项目混合 `src/content/docs/` 与 `src/pages/`。[页面指南](https://starlight.astro.build/guides/pages/) | + +### 方案 A：保留 `posts` collection，只统一 Starlight 页面壳 + +这是如果确实要统一 UI 时的推荐方案。 + +主要改动： + +1. 保留 `src/content/posts/{locale}/`、`posts` schema、现有 `/posts/...` URL 和 OG 图片 endpoint。 +2. 在 Starlight 配置中加入： + + ```js + markdown: { + processedDirs: ['./src/content/posts/'], + }, + ``` + +3. 将 `PostLayout.astro` 和 `PostListLayout.astro` 的外壳从 `BaseLayout` 改为 `StarlightPage`： + - Blog 页面通常传 `hasSidebar={false}`； + - 传入 `lang="en"` 或 `lang="zh-CN"`； + - 文章 route 从 `render(post)` 同时获取 `headings`，传给 `StarlightPage` 才能生成右侧 TOC； + - 通过 Starlight frontmatter/head 或条件组件 override 保留 article OG meta、动态 OG 图片、日期和 tags。 +4. 复用或删除当前 `.post-content` 规则，改用 Starlight Markdown 样式；保留 PostCard/list 的产品化外观。 +5. Blog 仍不属于 Starlight autogenerated sidebar；如需要侧边栏入口，要在 sidebar 中显式添加 link。官方文档明确说明 custom pages 不能加入自动生成的 sidebar group。[`` 限制](https://starlight.astro.build/guides/pages/#starlightpage-component) +6. 当前 Blog 的翻译配对、缺失翻译处理和列表筛选继续由 `src/i18n/` 与 `locale` 字段负责。 +7. Blog 页面不再加载包含 Tailwind preflight 的 `site.css`，只保留作用域明确的 Starlight/Tailwind 样式，避免污染 Starlight 的 cascade layers。 + +收益： + +- docs 与 Blog 共用 Starlight Header、语言/主题控件、内容宽度、Markdown 视觉和 Pagefind 标记。 +- 不迁移文章文件，不改变 URL，不改变 Blog schema，回滚简单。 +- Landing 和 404 可继续保持当前定制设计。 + +代价与风险： + +- 仍然存在 docs i18n 与 Blog i18n 两套内容配对逻辑。 +- 为保留现有 Nav/Footer/OG 细节，可能需要少量 Starlight component override。 +- `` 的 `headings`、sidebar、draft 和 edit URL 行为与 docs collection 页面不同，需要逐项测试。 + +粗略范围：6–10 个实现/测试文件；基础统一约 2–4 个开发日。若要求像素级复刻现有 Nav/Footer/动画，再增加约 1–2 个开发日。 + +### 方案 B：把 Blog 移入 Starlight `docs` collection + +技术上可行，但不推荐作为当前目标。 + +可行实现： + +1. 把英文文章移到 `src/content/docs/posts/`，中文文章移到 `src/content/docs/zh-cn/posts/`，URL 仍可保持 `/posts/...` 与 `/zh-cn/posts/...`。 +2. 用 `docsSchema({ extend })` 增加 `date`、`tags`、`kind: 'post'` 等字段。Starlight 官方支持扩展 docs frontmatter schema。[Frontmatter schema 扩展](https://starlight.astro.build/reference/frontmatter/#customize-frontmatter-schema) +3. 删除独立 `posts` collection 和文章 `[slug].astro` route，由 Starlight 自动生成文章页。 +4. Blog list、tags、archive 仍需要自定义 Astro 页面；collection 默认不保证日期排序，仍需 `getCollection()` 后自行筛选和排序。[Astro content collections](https://docs.astro.build/en/guides/content-collections/) +5. 条件 override `PageTitle`/`Footer`/`Sidebar` 或插入 MDX component，显示发布日期、标签、返回 Blog 链接和现有 OG 图片。 + +收益： + +- Blog 文章天然使用 Starlight Markdown、Pagefind、draft、翻译 fallback 和语言切换。 +- 文章页 route 可以少一个自定义实现。 + +代价与风险： + +- `docs` collection 同时承载 docs 与 Blog 两种 domain model，schema 和 UI override 更复杂。 +- Starlight 默认文章页是文档语义；要恢复当前 Blog 体验，需要条件化 sidebar、pagination、标题区和 article metadata。 +- Blog list、标签、RSS、OG 仍然没有消失，不能达到“只用 Starlight、不写 Astro”的目标。 +- 内容移动会扩大 review 面并增加 URL、canonical、hreflang、Pagefind 和 redirect 的回归面。 + +粗略范围：10–15 个实现/内容/测试文件；基础迁移约 3–5 个开发日。若同时补 RSS、tags/archive、Landing 和完整视觉对齐，约 5–8 个开发日。 + +### 方案 C：使用社区 `starlight-blog` + +官方插件目录确认有 `starlight-blog`，但它是社区维护插件。Starlight 0.41 的升级说明也明确提醒，社区 Starlight plugins 和 Astro integrations 可能需要针对 Astro 7 单独升级与核验。[Starlight 0.41.0 changelog](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md#0410) + +不建议把它作为本次 Astro 7 升级的前置依赖。只有在后续确认它覆盖双语 URL、现有 OG endpoint、tags、Cloudflare 和 Starlight 0.41，并做过锁版本验证后，才值得单独评估。 + +### 对调研一的最终判断 + +- “Starlight 替换 Astro”：**不可行，概念上也不成立。** +- “Starlight 统一 docs/blog 的外观与搜索”：**可行，推荐方案 A。** +- “所有内容统一到一个 collection”：**可行但收益不足，暂不推荐。** +- “Landing/docs/blog 全部改成 Starlight 页面”：会牺牲或重写当前 Landing 的 Hero、Features、Hook、Tape、Testimonials 等定制体验，而且底层仍是 Astro，不值得为“技术栈名称统一”而做。 + +## 调研二：升级到 Astro 7 要改什么 + +### 发布与兼容结论 + +Astro 7 已正式发布，默认使用 Vite 8、Rust `.astro` compiler、新的 Sätteri Markdown pipeline，以及新的 JSX 风格 HTML whitespace 处理。[Astro 7 发布说明](https://astro.build/blog/astro-7/)、[完整迁移指南](https://docs.astro.build/en/guides/upgrade-to/v7/) + +Starlight 版本必须同步跨代： + +- 0.38.x 支持 Astro 6； +- 0.39.x 仍是 Astro 6，但引入 sidebar `autogenerate` 结构变更； +- 0.40.x 增加 Sätteri 支持，最低 Astro 6.4.5； +- 0.41.x 支持 Astro 7，并停止支持 Astro 6。 + +来源：[Starlight changelog 0.39–0.41](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md#0410)。因此不能只把 `astro` 从 6 改成 7，必须同时更新 Starlight、Cloudflare adapter 和关联 Vite 插件。 + +### 依赖改动 + +截至 2026-08-12，建议使用下面这组已在隔离副本验证的版本： + +| 包/配置 | 当前 | 目标 | 是否必须 | 原因 | +|---|---:|---:|---|---| +| `astro` | 6.1.10 | 7.2.1 | 是 | Astro 7 当前稳定版。 | +| `@astrojs/starlight` | 0.38.3 | 0.41.7 | 是 | 0.38 只接受 Astro 6；0.41 接受 Astro 7。 | +| `@astrojs/cloudflare` | 13.1.10（range `^13.1.9`） | 14.2.1 | 是 | 14.x 对应 Vite 8/Astro 7；14.2.1 明确依赖 Astro ≥7.2.0 的新导出。[Cloudflare changelog](https://github.com/withastro/astro/blob/main/packages/integrations/cloudflare/CHANGELOG.md#1421) | +| `astro-mermaid` | 2.0.1 | 2.1.0 | 是 | 2.0.1 写入旧 remark/rehype 数组，Astro 7 默认 Sätteri 不执行；2.1.0 增加 Sätteri 分支。[v2.1.0 source](https://github.com/joesaby/astro-mermaid/blob/v2.1.0/astro-mermaid-integration.js) | +| `@tailwindcss/vite` | 4.2.2（range `^4.1.14`） | 4.2.2 | 否 | 当前 lock 已是包含 Vite 8 peer range 的版本。 | +| `tailwindcss` | 4.2.2（range `^4.1.14`） | 4.2.2 | 否 | 当前解析版本可保持。 | +| `@lucide/astro` | 1.8.0 | ≥1.31.0 | 是 | 1.8 peer range只到 Astro 6；1.31 包含 Astro 7。 | +| `wrangler` | 4.83.0（range `^4.13.2`） | 4.121.0 | 是 | 本次解析到的新 `@cloudflare/vite-plugin` peer 要求 `wrangler ^4.121.0`。 | +| `@astrojs/starlight-tailwind` | 5.0.0 | 5.0.0 | 否 | peer 为 Starlight ≥0.38 + Tailwind 4，可继续使用。 | +| `overrides.vite` | `^7.3.2` | 删除 | 是 | Astro 7 自带 Vite 8；强制 Vite 7 会制造不兼容。 | + +版本与 peer metadata 可在 npm registry 的对应发布记录核对：[Astro 7.2.1](https://registry.npmjs.org/astro/7.2.1)、[Starlight 0.41.7](https://registry.npmjs.org/%40astrojs%2Fstarlight/0.41.7)、[Cloudflare adapter 14.2.1](https://registry.npmjs.org/%40astrojs%2Fcloudflare/14.2.1)、[Tailwind Vite plugin 4.2.2](https://registry.npmjs.org/%40tailwindcss%2Fvite/4.2.2)、[Lucide Astro 1.31.0](https://registry.npmjs.org/%40lucide%2Fastro/1.31.0)、[Wrangler 4.121.0](https://registry.npmjs.org/wrangler/4.121.0)。 + +建议用 `pnpm dlx @astrojs/upgrade` 更新 Astro 与官方 integrations，再显式更新 community/非官方包并检查 lockfile；官方迁移指南推荐使用 upgrade CLI，但它不会替你解决所有第三方 integration 兼容性。 + +### 必须改的配置 + +Starlight 0.39 已把 sidebar group 的 `autogenerate` 包进 `items`。当前 6 个 group 都要改： + +```diff +{ + label: 'Getting Started', + translations: { 'zh-CN': '快速开始' }, +- autogenerate: { directory: 'docs/getting-started' }, ++ items: [{ autogenerate: { directory: 'docs/getting-started' } }], +} +``` + +同样修改 `Concepts`、`Operate`、`Build`、`Tutorials`、`Reference`。这是 Starlight 0.39 的明确 breaking change。[0.39.0 changelog](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md#0390) + +除此之外，当前 Cloudflare `imageService`、`prerenderEnvironment: 'node'`、content loaders、`envField`、动态 locale routes 和 OG endpoint 在隔离构建中都可保持不变。 + +因此纯 Astro 7 升级的预期必改文件只有： + +- `website/package.json`：更新版本并删除 Vite override； +- `website/pnpm-lock.yaml`：刷新完整解析结果； +- `website/astro.config.mjs`：修改 6 个 sidebar group； +- `website/AGENTS.md`：同步版本和 sidebar/Markdown 约定。 + +`src/pages/`、`src/layouts/`、`src/components/`、`src/content.config.ts` 和现有 Markdown/MDX 内容在隔离验证中均无需为 Astro 7 做强制源码修改。 + +### Astro 7 breaking changes 对本仓库的逐项影响 + +| Astro 7 变化 | 仓库影响 | 处理 | +|---|---|---| +| Vite 8 / Rolldown | 有 | 删除 Vite 7 override；升级 Cloudflare adapter；当前 `@tailwindcss/vite` 4.2.2 可保留。 | +| Rust `.astro` compiler 更严格 | 暂无代码改动 | 隔离构建已通过，说明当前 `.astro` 没有阻断性未闭合标签/语法；仍需视觉检查非法 HTML nesting。 | +| 默认 Markdown processor 改为 Sätteri | 有 | 升 `astro-mermaid` 2.1.0；无需切回 unified。隔离构建确认 6 个 Mermaid block 被 Sätteri 转换。 | +| `compressHTML` 默认从 `true` 变为 `'jsx'` | 潜在视觉影响 | 检查相邻 inline element 的空白。隔离副本的中英文 Landing 可见文本未发现丢空格，建议接受新默认；只有发现回归时才临时设 `compressHTML: true`。 | +| `src/fetch.ts` 成为保留文件 | 无 | 仓库没有该文件。 | +| experimental flags 稳定/移除 | 无 | config 没有相关 experimental flags。 | +| Container renderer import 路径弃用 | 无 | 未使用 Container API。 | +| 移除 `@astrojs/db` | 无 | 未依赖。 | +| 移除部分 `astro:transitions` internals | 无 | 未使用这些 API。 | +| Node engine | 无 | Astro 7 要求 Node ≥22.12；`package.json` 已是 `>=22.12.0`，部署文档的 22.16.0 也满足。 | + +完整变化及保留旧 Markdown/whitespace 行为的方法见[官方 v7 迁移指南](https://docs.astro.build/en/guides/upgrade-to/v7/)。 + +另外，Vite 8 的底层 bundler/minifier 已换为 Rolldown/Oxc，并默认使用 Lightning CSS，CommonJS interop 也有调整；本仓库没有自定义 `rollupOptions`、esbuild API 或 integration hooks，因此没有额外代码迁移项，但视觉回归不应把等价的 CSS 序列化差异当作失败。详见[Vite 8 官方迁移指南](https://vite.dev/guide/migration.html)。Vite 8 与 Starlight 0.41 还提高了支持的浏览器基线；如果项目另有旧浏览器 SLA，需要在实施前单独确认。[Starlight 0.41.0 release](https://github.com/withastro/starlight/releases/tag/%40astrojs%2Fstarlight%400.41.0) + +### 还应更新的仓库文档 + +升级实现完成后同步修改： + +- `website/AGENTS.md`：Astro 6 → Astro 7；Starlight 最低版本；Markdown processor 说明；sidebar 新结构。 +- `website/astro.config.mjs` 中“Astro v6 scopes CSS...”的注释：代码可继续工作，但应改成不绑定 major 的说明，避免误导。 +- `website/DEPLOYMENT.md`：Node 版本无需变，但应确认 Wrangler/Cloudflare 构建说明仍与生成的 redirected config 一致。 +- 如升级 PR 接受 `compressHTML: 'jsx'`，记录 inline whitespace 约束；如暂时保留 `true`，记录它是兼容开关。 + +### 隔离升级验证 + +没有改工作区源码；在 `/tmp` 复制 `website/` 后进行了两阶段验证。 + +第一次只升级核心依赖，准确复现两个问题： + +1. Starlight 拒绝当前 `sidebar.*.autogenerate` shape； +2. `astro-mermaid` 2.0.1 写入的 remark/rehype plugins 不会被默认 Sätteri 执行。 + +完成依赖表和 sidebar 改动后： + +| 验证 | 结果 | +|---|---| +| `BUB_ASTRO_IMAGE_MODE=build pnpm exec astro build` | 通过 | +| Rust compiler 处理全部 `.astro` | 通过，无需源码语法修复 | +| 6 个中英文 Mermaid diagrams | Sätteri 日志确认全部转换 | +| Starlight Pagefind | 构建完成 | +| Cloudflare image compile/passthrough 配置 | 构建通过 | +| `pnpm preview`，Wrangler 4.121 redirected config | 启动成功 | +| `/` | 200 | +| `/docs/getting-started/` | 200 | +| `/posts/why-rewrite-bub/` | 200 | +| `/zh-cn/docs/getting-started/` | 200 | + +另一份隔离验证还完成了 `wrangler deploy --dry-run`，成功生成 Worker，gzip 上传体积约 2.5 MiB。这证明升级不需要重写 pages/content API；主要工作集中在依赖矩阵、sidebar shape 和视觉/部署回归。 + +对 Astro 6/7 的 77 个静态 HTML 做文本对比时，有 7 页出现 Sätteri/SmartyPants 展示差异，主要是中文直引号变弯引号，以及代码示例中 YAML 冒号周围的展示空格： + +- `/docs/getting-started/first-skill/` +- `/zh-cn/docs/build/skills/` +- `/zh-cn/docs/getting-started/first-skill/` +- `/zh-cn/docs/operate/channels/telegram/` +- `/zh-cn/docs/reference/settings/` +- `/zh-cn/posts/bootstrap-milestone/` +- `/zh-cn/posts/socialized-evaluation/` + +没有正文缺失或路由数量变化，但上线前应人工抽查这 7 页。若必须逐字节保持旧 Markdown 输出，可显式安装 `@astrojs/markdown-remark` 并切回 `unified()`；本项目没有这项需求时，继续使用 Sätteri 更简单。 + +### 正式升级的建议顺序 + +1. 创建只包含工具链的变更：更新依赖、删除 Vite override、刷新 `pnpm-lock.yaml`。 +2. 修改 6 个 Starlight sidebar group。 +3. 更新 `AGENTS.md`/部署说明。 +4. 运行： + + ```bash + pnpm install --frozen-lockfile + make docs-test + make check + pnpm --dir website exec wrangler deploy --dry-run + ``` + +5. 用 `make docs` 检查 dev/HMR；用 `make docs-preview` 检查 generated Worker。 +6. 至少人工检查下列中英文页面：Landing、Blog list、Blog article、普通 docs、含 Mermaid 的 docs、404。 +7. 检查 light/dark、语言切换、搜索、移动导航、canonical/hreflang/OG、字体与 inline whitespace。 +8. 做一次 Cloudflare preview deployment，再合并。 +9. Astro 7 稳定后，另起变更试做 Blog ``；不要同时移动 Blog collection。 + +## 最终建议 + +本次应该选择 **“升级 Astro 7，暂不把 Blog 迁进 Starlight docs collection”**。 + +理由不是 Starlight 不好，而是当前架构已经正确使用了它：Starlight 管文档，Astro 管产品化 Landing 和 Blog。直接迁移 Blog 到 `docs` collection 不会消除 Astro，也不会消除日期、标签、列表、OG 和 i18n 逻辑，反而会把 Blog 特有逻辑塞入 Starlight override。若真正痛点是视觉和搜索不统一，用 `` 包装现有 Blog 是更小、更可逆的后续改动。 + +Astro 7 升级本身已经通过隔离构建、本地 Worker 冒烟与 deploy dry-run 验证，具备直接实施条件。预计实现 30–60 分钟，完整中英文视觉与 Cloudflare 验证约 2–4 小时，可按半个工程日排期。