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 与根目录 site 连接到 socai-io/socai。

故障排查

多提交推送后网站更改被跳过

site/vercel.json 中忽略构建步骤的配置必须将 HEAD 与 VERCEL_GIT_PREVIOUS_SHA（该项目和分支最后一次成功部署的 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 预览