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 — 型別檢查語系字典；CI 關卡
pnpm run build # → site/dist
pnpm run dev
URL 與 SEO 合約 (容易靜默失效的部分)
一切只在以下條件保持一致時才能正常運作：
build.format: 'preserve'→ 扁平頁面會建置成changelog.html，語系根目錄則為ru/index.html(目錄形式)。- 正典化 (Canonical) 格式：扁平頁面以
.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) 以便於 SEO 稽核時使用 grep 搜尋；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 驗證標籤位於版面 head 中 — 請勿移除它們。
- 網站文案 (以及所有其他使用者面向的表面 — README、plugin.json、倉儲中繼資料) 的用詞/定位規則位於
seo-surfaces技能 + AGENTS.md "SEO surfaces" 中。CI：node scripts/seo-check.mjs --site在 Pages 工作流程中針對dist/執行。