Astro 站点 (site/)
独立的 pnpm 项目（拥有自己的 lockfile，不属于插件构建的一部分）。使用 Astro + @astrojs/sitemap + @astrojs/check。部署到 GitHub Pages：https://vadimonix.github.io/xray-decky/。
cd site
pnpm install
pnpm run check # astro check — 类型检查 locale 字典；CI 门控
pnpm run build # → site/dist
pnpm run dev
URL 与 SEO 契约（容易静默损坏的部分）
一切正常运行的前提是以下内容保持一致：
build.format: 'preserve'→ 平面页面构建为changelog.html，区域根目录构建为ru/index.html（目录形式）。- 规范链接形式：平面页面以
.html结尾；区域根目录使用尾部斜杠（…/ru/）；站点根目录为…/xray-decky/。由src/lib/urls.ts（absoluteUrl、withBase、localeHref）生成。 - Sitemap 必须与规范链接的字符串完全匹配。
astro.config.mjs中的serialize钩子会重写<loc>和自动生成的 hreflang<xhtml:link>替代项：区域根目录路径段（LOCALE_DIRS）获得/，其他无扩展名的内容获得.html。历史：在 2026-08 之前，它只重写<loc>并直接添加.html扩展名，导致爬虫访问不存在的ru.html/zh.html/fa.html/es.html。 - Sitemap 的 hreflang 集合必须等于页面的 hreflang 集合。
Base.astro发出 5 种语言 +x-default；集成只发出 5 种，因此serialize会附加x-default（即enURL）。Google 会读取这两种传递方式的注解，并将不同的集合视为冲突，而不是子集。seo-check --site会按 URL 对它们进行比较。 - 此部署中的 robots.txt 不生效。 它会被部署到
/xray-decky/robots.txt，但爬虫只读取https://vadimonix.github.io/robots.txt，该地址返回 404（没有用户站点仓库）—— 404 意味着“爬取所有内容”，因此没有任何内容被阻止，但Sitemap:行永远不会被看到。Sitemap 发现完全依赖于 Search Console 提交。真正的修复方法（在此仓库之外）是：创建一个VadimOnix/vadimonix.github.io仓库来提供主机根目录的 robots.txt，或者使用自定义域名。 - GitHub Pages 是宽容的（无扩展名文件 → 200，没有斜杠的目录 → 301）—— 永远不要依赖于此；请精确匹配规范链接。
compressHTML: false是故意的：保持<head>（规范链接、hreflang、OG、JSON-LD）可 grep 以便进行 SEO 审计；gzip 可以恢复大小。
添加一种语言只需修改一处：src/i18n/locales.ts（LOCALES、localePrefixes、hreflangCodes）+ 由 src/i18n/types.ts 类型化的字典文件 + astro.config.mjs 中的 LOCALE_DIRS + sitemap 集成配置中的 locales 映射。缺少字典键时 astro check 会失败——这就是 CI 在构建之前运行它的原因。
部署
.github/workflows/pages.yml：在推送到 master 分支且修改涉及 site/**（或工作流本身）时触发。Node 22，pnpm 9，--frozen-lockfile，check → build → 上传 site/dist → 部署。没有 PR 构建——PR CI 不构建站点，因此绿色 PR 对站点没有任何意义。
验证 Astro 大版本升级（经验法则，而非阅读更新日志）
Dependabot 只升级 astro——对等集成（@astrojs/sitemap、@astrojs/check）会滞后；请验证它们是否仍然有效，而不是盲目假设。
- 在本地构建升级后的版本：
pnpm install --frozen-lockfile && pnpm run check && pnpm run build。 - 对比
dist/布局与之前的构建（相同的 11+ 路由，区域目录保持不变，没有内容被扁平化）。 grep -o '<loc>[^<]*</loc>' dist/sitemap-0.xml——每个 URL 必须匹配实际文件的规范链接形式。- 抽查
dist/index.html和一个语言页面中的<link rel="canonical">和 hreflang。 - 合并后，观察 Pages 运行并探测实时 URL（
curl -s -o /dev/null -w "%{http_code}"）。
已知阈值：Astro 6 需要 Node ≥22（pages.yml 已经在使用 22）并弃用了 CJS 配置（我们的是 .mjs）；i18n.routing.redirectToDefaultLocale 默认值已更改（此处无关——prefixDefaultLocale: false）。Astro 7 已迁移到 Vite 8/Rolldown + Rust 编译器——主要影响集成/自定义 Vite 配置，此站点没有这些。升级指南：https://docs.astro.build/en/guides/upgrade-to/v6/，https://docs.astro.build/en/guides/upgrade-to/v7/。
杂项
optimize-images.sh——用于public/的图像管道；添加大型资源后运行。- Search Console / Yandex 验证标签位于布局头部——请勿删除。
- 站点文案（以及所有其他用户可见的表面——README、plugin.json、仓库元数据）的措辞/定位规则存在于
seo-surfaces技能 + AGENTS.md "SEO surfaces" 中。CI：node scripts/seo-check.mjs --site在 Pages 工作流中针对dist/运行。