socai-io/socai

socai 網站部署

當任務涉及 socai 網站部署、Vercel 配置、socai.io、www.socai.io、/download、/github 或 PR 預覽部署時，請使用此技能。

此技能是部署操作手冊的權威來源。../../../docs/website-deployment.md 刻意保持簡短，並指向此處，以避免重複指示導致偏移。

專案背景

• 網站原始碼：site/
• 框架：Astro 靜態網站
• Vercel 團隊/範圍：socai-d83824c8 (socai)
• Vercel 專案：socai-site
• 正式網域：https://socai.io
• 文件路由：https://socai.io/docs/（使用 Astro 網站建置的 Starlight 頁面）
• 標準主機：socai.io
• www 行為：https://www.socai.io/* 應回傳 308/重新導向至 https://socai.io/*
• 下載路由：https://socai.io/download 重新導向至 socai OSS 發佈鏡像上的最新通用 macOS DMG
• GitHub 路由：https://socai.io/github 重新導向至 https://github.com/socai-io/socai

預期的 Vercel 專案設定：

設定	值
框架預設	Astro
根目錄	site
安裝命令	pnpm install
建置命令	pnpm build
輸出目錄	dist
Node.js 版本	24.x

安全規則

• 所有 Vercel 專案/網域命令都使用 socai-d83824c8 範圍。
• 不要從錯誤的 Vercel 團隊或個人專案部署。
• 不要提交 site/.vercel/、site/dist/、site/.astro/ 或 site/node_modules/。
• 除非使用者明確同意，否則不要啟用分析功能。
• 在進行網站部署工作時，不要編輯應用程式版本資產。
• 在專用分支上處理議題，並為儲存庫變更開啟/更新 PR。
• 如果為了手動部署而暫時變更 Vercel 專案設定，請在完成後恢復。

本地驗證

在部署或開啟與部署相關的程式碼/設定的 PR 之前：

cd site
pnpm install
pnpm build

在修改 JSON/XML 設定時進行驗證：

python3 -m json.tool site/vercel.json >/dev/null
python3 -m json.tool site/public/site.webmanifest >/dev/null
python3 - <<'PY'
import xml.etree.ElementTree as ET
ET.parse('site/dist/sitemap-index.xml')
ET.parse('site/dist/sitemap-0.xml')
PY

檢查 Vercel 狀態

vercel whoami
vercel teams ls
vercel projects ls --scope socai-d83824c8
vercel project inspect socai-site --scope socai-d83824c8 --yes
vercel domains inspect socai.io --scope socai-d83824c8
vercel domains inspect www.socai.io --scope socai-d83824c8

確認專案設定顯示根目錄 site、框架 Astro、建置命令 pnpm build、輸出 dist、安裝 pnpm install。

首選正式部署

啟用 Git 整合後的首選路徑：

1. 將網站變更合併到 main。
2. 讓 Vercel 從根目錄 site 建置 socai-site 專案。
3. 使用以下命令驗證正式 URL。

PR 預覽也需要在 Vercel 儀表板中連接 Git 整合。

緊急/手動 CLI 正式部署

由於 Vercel 專案設定了根目錄 site，直接從 site/ 進行本地部署可能會出現 site/site 根目錄錯誤。如果 Git 整合不可用，且需要 CLI 部署，請使用此臨時根目錄解決方案，並在完成後恢復根目錄設定。

set -euo pipefail

cat > /tmp/vercel-root-null.json <<'EOF'
{
  "rootDirectory": null
}
EOF
cat > /tmp/vercel-root-site.json <<'EOF'
{
  "rootDirectory": "site"
}
EOF

restore_root() {
  vercel api /v10/projects/socai-site \
    --scope socai-d83824c8 \
    -X PATCH \
    --input /tmp/vercel-root-site.json \
    --silent || true
}
trap restore_root EXIT

vercel api /v10/projects/socai-site \
  --scope socai-d83824c8 \
  -X PATCH \
  --input /tmp/vercel-root-null.json \
  --silent

cd site
vercel deploy --prod --scope socai-d83824c8 --project socai-site --yes

部署後，確認根目錄已恢復：

vercel project inspect socai-site --scope socai-d83824c8 --yes

不要將專案保留為 Root Directory . 或 null；Git 預覽依賴於 site。

URL 驗證

首先使用 HEAD 檢查：

curl -I https://socai.io/
curl -I https://socai.io/docs/
curl -I https://socai.io/docs/quickstart/
curl -I https://www.socai.io/
curl -I https://socai.io/sitemap.xml
curl -I https://socai.io/sitemap-index.xml
curl -I https://socai.io/download
curl -I https://socai.io/github

預期的第一跳行為：

• https://socai.io/ 回傳 200。
• https://socai.io/docs/ 回傳 200，且巢狀頁面如 /docs/quickstart/ 回傳 200。
• https://www.socai.io/ 回傳 308，且 location: https://socai.io/。
• https://socai.io/sitemap.xml 永久重新導向至 /sitemap-index.xml，後者回傳 200。
• https://socai.io/download 回傳 Vercel 重新導向 (307) 至已設定的 OSS 發佈鏡像上的最新通用 macOS DMG。
• https://socai.io/github 回傳 Vercel 重新導向 (307) 至 https://github.com/socai-io/socai。

只有在想要追蹤重新導向鏈時才使用 -L：

curl -I -L --max-time 30 -o /dev/null -w 'code=%{http_code}\nfinal=%{url_effective}\n' https://socai.io/download

Git 預覽設定

嘗試：

cd site
vercel link --yes --scope socai-d83824c8 --project socai-site
vercel git connect https://github.com/socai-io/socai --scope socai-d83824c8

如果 Vercel 回傳：

Failed to link socai-io/socai. You need to add a Login Connection to your GitHub account first.

則需要由 Vercel/GitHub 帳戶擁有者在 Vercel 儀表板中連接 GitHub 登入/整合，然後將 socai-site 連接到 socai-io/socai，根目錄設定為 site。

故障排除

多次提交推送後網站變更被跳過

site/vercel.json 中的忽略建置步驟必須將 HEAD 與 VERCEL_GIT_PREVIOUS_SHA（此專案與分支的最後一次成功部署）進行比較，而不是 HEAD^。一次推送中的最後一次提交可能只變更 Rust 程式碼，而先前的提交則變更網站。如果先前的部署 SHA 不存在或在淺層克隆中不可用，則建置而非跳過。退出碼 0 跳過建置；退出碼 1 則繼續。

Root Directory "site" does not exist

這通常發生在從 site/ 執行本地 CLI 部署，而遠端專案也將根目錄設定為 site 時。請使用上述的緊急/手動 CLI 部署解決方案，或選擇 Git 部署。

上傳的檔案過多

從儲存庫根目錄部署可能會包含 Rust/Python 建置成果，並超過 Vercel 的檔案數量限制。除非有經過測試的忽略/封存策略，否則不要直接從儲存庫根目錄部署。建議選擇 Git 部署，或使用臨時根目錄重設從 site/ 進行緊急/手動部署。

www.socai.io 回傳 200 而非重新導向

確保最新的正式部署在主機重新導向中包含 site/vercel.json，然後重新部署。使用以下命令驗證：

curl -I https://www.socai.io/

GitHub 最新版本中繼資料不可用

網站仍應顯示一般的非過期副本（latest release），且 /download 仍應重新導向至 GitHub 的最新版本資產。

回報

回報部署任務時，請包含：

• 分支/PR（如果儲存庫檔案已變更）
• 已確認的 Vercel 專案設定
• 部署 URL 及正式網域
• 已執行的命令
• 針對 /、/docs/、/docs/quickstart/、www、/download 和 /github 的驗證輸出摘要
• 任何殘留的手動障礙，尤其是 Git 整合/PR 預覽