{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Publish Site

版本化站点部署到 GitHub/Cloudflare/Netlify Pages。

Skill 元数据

参考：完整 SKILL.md

Publish Site

把用户建的（或你替他们建的）一个网站、仪表盘或 web 应用，放到用户自己拥有的基础设施上线——默认 GitHub Pages，需要更多时用 Cloudflare Pages 或 Netlify。纪律是：本地预览待确认、用 git tag 给每次部署打版本、沿提供商阶梯部署、用真实 HTTP 检查验证线上 URL、并让回滚只有一条命令之遥。

本 skill 覆盖静态站点和 SPA 构建产物（纯 HTML/CSS/JS，或 Vite/Next-export/Astro 等的 dist//build/ 目录）。它不覆盖服务端运行时——要零账号配置的一次性 serverless 部署，改用 cloudflare-temporary-deploy 可选 skill。

使用时机

当用户要求以下能力时加载本 skill：

• 把站点上线——"发布这个"、"把它托管到某处"、"给我一个能分享的链接"
• 部署你刚生成的仪表盘、报告、作品集、文档站或原型
• 更新已发布的站点（重新部署 = 新版本）
• 回滚一次坏部署到上一版本
• 选个主机——他们不在乎在哪，只要一个 URL

前提条件

至少一个已认证的提供商 CLI（按此顺序检查）：

• GitHub Pages（默认）： gh auth status 成功。还需要 git。
• Cloudflare Pages： wrangler whoami 成功（或设了 CLOUDFLARE_API_TOKEN）。安装：npm i -g wrangler 或用 npx wrangler@latest。
• Netlify（回退）： netlify status 成功。安装：npm i -g netlify-cli。

另需：

• 一个要发布的静态输出目录（站点根目录或 dist//build/ 目录）。如果项目需要构建步骤，先构建再发布输出目录，绝不发布源码。
• 本地预览分享：cloudflared（可选——python3 -m http.server 覆盖仅本地预览）。

运行方式

下面所有命令都通过 terminal 工具在站点项目目录内运行。流水线始终是同样五步：

1. 构建 → 2. 预览待确认 → 3. 提交 + 打 tag（先版本后部署）→ 4. 沿提供商阶梯部署 → 5. 用 curl 验证线上 URL 并报告。

快速参考

流程

1. 本地构建并预览

需要就构建（npm run build 等）并确定输出目录。服务它：

python3 -m http.server 8080 --directory dist

要一个可分享的预览链接（用户在另一台机器上，或你想在上线前让他们确认），在后台 terminal 会话开一条快速隧道：

cloudflared tunnel --url http://localhost:8080

把 https://*.trycloudflare.com URL 给用户，部署前拿到确认。之后关掉隧道。

2. 部署前打版本——没有例外

每次部署都必须来自一个 git commit，这样每次部署可复现、回滚轻而易举。

git init 2>/dev/null; git add -A
git commit -m "deploy: <简短描述>"
git tag "deploy-$(date +%Y%m%d-%H%M)"

如果项目已有仓库，只需提交 + 打 tag。绝不部署未提交的文件。

3. 部署——提供商阶梯

第 1 阶——GitHub Pages（默认：免费，若 gh 已认证则无需额外账号）：

gh repo create <name> --public --source . --push   # 仓库已存在则跳过
git subtree push --prefix dist origin gh-pages      # 发布构建产物
gh api "repos/{owner}/<name>/pages" -X POST \
  -f 'source[branch]=gh-pages' -f 'source[path]=/'  # 仅首次

站点出现在 https://<owner>.github.io/<name>/。如果站点就是仓库根目录（无构建目录），推送 main 并把 Pages 源设为 main，而不用 subtree。对于会频繁重新部署的构建步骤项目，优先用官方 actions/deploy-pages workflow，让推送自动发布。

第 2 阶——Cloudflare Pages（当用户要自定义域名、重定向/响应头或 Functions 时）：

npx wrangler@latest pages deploy dist --project-name <name>

首次运行创建项目并打印 https://<name>.pages.dev URL。自定义域名通过 Cloudflare dashboard 挂载（Pages → project → Custom domains）。

第 3 阶——Netlify（回退，或用户本就在用它）：

netlify deploy --prod --dir dist

netlify deploy --dir dist（不带 --prod）给一个草稿 URL——可作为第二预览阶段。

4. 回滚

回滚 = 重新部署一个旧 tag。绝不手改线上产物。

git checkout deploy-<previous> -- .   # 或：git checkout deploy-<previous>; 重新构建
# 然后重跑第 3 步的同一条部署命令

Cloudflare Pages 和 Netlify 也在各自 dashboard 里保留每次部署的历史（"Rollback to this deploy"），CLI 不在手边时更快。

5. 机密与环境变量

• 绝不提交机密、API key 或 .env 文件——它们会在 Pages 托管上公开。首次提交前用 git status 检查，把 .env* 放进 .gitignore。
• 运行时环境变量放在提供商 dashboard：Cloudflare Pages → Settings → Environment variables；Netlify → Site settings → Environment variables。GitHub Pages 仅静态——无服务端环境；任何内嵌进 bundle 的东西按定义就是公开的。如果你的构建把 key 内联了，警告用户。

常见陷阱

• SPA 路由在 GitHub Pages 上 404。 Pages 没有重写规则。把 index.html 复制为输出目录里的 404.html（cp dist/index.html dist/404.html），让客户端路由恢复。Cloudflare Pages 和 Netlify 通过 _redirects（/* /index.html 200）处理 SPA。
• GitHub Pages 构建延迟。 首次启用后站点可能要 1–10 分钟才出现，之后每次推送约 1 分钟。不要在第一次 404 就宣告失败——调查前先 curl 轮询几次。
• 大小写敏感路径。 Pages 托管是大小写敏感的 Linux；一个在 macOS/Windows 上正常的站点，会因资源按 Logo.PNG 引用却提交为 logo.png 而 404。资源 404 时 grep HTML 找大小写不匹配。
• 项目页 base 路径。 https://<owner>.github.io/<name>/ 在 /<name>/ 下服务——像 /app.js 这样的绝对资源 URL 会坏。用相对路径或设构建工具的 base（vite build --base=/<name>/）。
• wrangler 认证流程需要浏览器。 wrangler login 打开 OAuth；在无头会话里优先用 CLOUDFLARE_API_TOKEN（用户在 dash.cloudflare.com → API Tokens 创建），永不把 token 回显到日志。
• 自定义域名的 DNS 传播。 新 CNAME 可能要几分钟到几小时。先对照提供商默认 URL（*.pages.dev、*.netlify.app、*.github.io）验证，再单独查自定义域名——不要把两种失败混为一谈。
• 部署了源码而非构建产物。 真正的站点在 dist/ 却发布仓库根目录，会得到一个目录列表或裸 JSX。始终确认输出目录含 index.html。

验证

不要只凭部署日志报告成功。在告诉用户任何事之前：

1. curl -sS -o /dev/null -w '%{http_code}' <live-url> 返回 200（首次 GitHub Pages 部署在约 2 分钟内重试）。
2. curl -sS <live-url> | head -30 显示预期的 index.html 内容——可选地用 web_extract 对线上 URL 确认标记。
3. 对 SPA，再 curl 一个深层路由（如 /about）确认返回 200 而非 404。
4. git tag --list 'deploy-*' 显示本次部署的 tag。

然后把线上 URL 报告给用户，并附上他们可回滚到的部署 tag。