VadimOnix/xray-decky

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은 canonical과 문자열이 일치해야 합니다. 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(= en URL)를 추가합니다. Google은 두 전달 방법의 주석을 모두 읽고, 세트가 다른 경우 충돌로 간주합니다(하위 집합으로 보지 않음). seo-check --site는 이를 URL별로 비교합니다.
• robots.txt는 이 배포에서 무효합니다. /xray-decky/robots.txt로 전달되지만, 크롤러는 https://vadimonix.github.io/robots.txt만 읽으며, 이는 404를 반환합니다(사용자 사이트 저장소 없음) — 404는 "모든 것을 크롤링"을 의미하므로 차단되는 것은 없지만, Sitemap: 줄은 절대 볼 수 없습니다. Sitemap 검색은 전적으로 Search Console 제출에 의존합니다. 이 저장소 밖에서의 실제 수정: 호스트 루트 robots.txt를 제공하는 VadimOnix/vadimonix.github.io 저장소 또는 사용자 정의 도메인이 필요합니다.
• GitHub Pages는 관대합니다(확장자 없는 파일 → 200, 디렉토리에 슬래시 없음 → 301) — 이에 의존하지 말고 canonical과 정확히 일치시키십시오.
• compressHTML: false는 의도적입니다: SEO 감사 시 <head>(canonical, hreflang, OG, JSON-LD)를 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: site/** (또는 워크플로우 자체)를 변경하는 master 브랜치 푸시 시 트리거됩니다. Node 22, pnpm 9, --frozen-lockfile, check → build → site/dist 업로드 → 배포. PR 빌드 없음 — PR CI는 사이트를 빌드하지 않습니다, 따라서 PR 통과가 사이트에 대해 아무것도 말해주지 않습니다.

Astro 메이저 버전 업그레이드 확인 (변경 로그 읽기가 아닌 경험적 방법)

Dependabot은 astro만 업데이트합니다 — 피어 통합 패키지(@astrojs/sitemap, @astrojs/check)는 뒤처집니다; 가정하지 말고 여전히 작동하는지 확인하십시오.

1. 업데이트된 버전을 로컬에서 빌드: pnpm install --frozen-lockfile && pnpm run check && pnpm run build.
2. dist/ 레이아웃을 이전 빌드와 비교 (동일한 11개 이상의 라우트, 로케일 디렉토리 유지, 평탄화 없음).
3. grep -o '<loc>[^<]*</loc>' dist/sitemap-0.xml — 모든 URL이 실제 파일의 canonical 형식과 일치해야 합니다.
4. dist/index.html과 하나의 로케일 페이지에서 <link rel="canonical"> 및 hreflang을 스팟 체크합니다.
5. 병합 후 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/에 대해 실행됩니다.