发布看起来只是把文件丢到平台上，但这里最容易出一些很现实的事故。

在 Idea2Site 里，发布相关的 skill 是：

publish-static-site

它负责把一个已经完成的静态个人网站，准备或发布到常见平台：

  • GitHub Pages
  • Cloudflare Pages
  • Netlify
  • Vercel

它也可以处理 framework 项目的静态输出，但默认姿态依然是：

简单静态托管优先。
部署时保持纯静态站的形态。

我觉得这个 skill 很重要，因为很多建站项目真正翻车常常发生在发布那一刻。本地看起来好好的，一上线就全变了。

本地看起来没问题，发出去之后：

  • CSS 404；
  • 文章页 404；
  • GitHub Pages 子路径错；
  • deploy root 选错；
  • 上传了 .env；
  • 发布目录里没有 index.html；
  • 原站作者信息还在；
  • Vercel/Netlify 配置指向了错误输出目录。

所以 publish-static-site 的目标很明确：

确认这个静态站真的适合被公开托管，然后再选择最简单可靠的平台和部署方式。

1. publish-static-site 的边界

这个 skill 的职责边界很清楚，遇到下面这些问题就回到对应模块：

  • 重新设计网站；
  • 修正文案；
  • 导入文章；
  • 替换个人身份；
  • 重做页面；
  • 绕过本地路径问题；
  • 未授权创建仓库、push、绑定域名、改 DNS。

这些事情都有对应 skill。发布层专心处理发布，这样问题更容易追。

如果发布前发现内容问题，就回到：

personalize-site
add-blog-posts
edit-site-part
make-personal-site
copy-website-style
review-static-site

发布层聚焦发布。

这点很关键。发布是外部状态改变，比本地改文件要谨慎很多。

因为很多 Agent 一看到用户说“发布吧”，就会尝试直接 push 或部署。这样很危险，尤其是当前 worktree 里可能有用户其他文件、私密草稿、临时文件。

所以 publish-static-site 的默认姿态很保守：

远程动作需要明确授权。
review 需要通过，或者风险需要显式说明。
deploy root 顶层需要有 index.html。
deploy root 需要明确。

2. 发布前先 review

publish-static-site 的 success gate 第一条就是：

review-static-site has passed or unresolved risks are explicit.

也就是说，发布前最好先跑 review-static-site。这一步我觉得非常关键。

为什么？

因为部署解决不了本地问题。本地已经坏了，发出去只是换一个地方坏。

如果本地路径已经错了，发布之后只会更难排查。

如果本地源码有乱码，发布之后依旧会保留这个问题。

如果 deploy root 里有私密文件，发布之后就已经公开了。

所以发布前要确认：

  • deploy root 顶层有 index.html；
  • 本地 HTTP 能打开；
  • direct-open 没有明显路径问题；
  • CSS、JS、图片、字体都在 deploy root 内；
  • 子页面能访问；
  • 没有 accidental root-absolute site-local path；
  • 没有 .env、token、私钥、本机路径；
  • placeholder 和源站残留已经清理或明确接受。

这就是发布前门禁。

3. Deployment Modes

publish-static-site 把发布请求分成几种模式。

3.1 Guidance only

用户只是问：

这个站怎么发布？
我应该选哪个平台？
Cloudflare Pages 怎么填？

这时候保持文件不动，给用户清楚的设置就够了。

给出明确设置即可。

比如：

Platform: Cloudflare Pages
Build command: none
Build output directory: site
Root directory: repository root

3.2 Prepare repo

用户想让 Agent 准备配置文件，但还不想直接远程操作。

这时候可以添加：

  • GitHub Pages workflow；
  • .nojekyll；
  • netlify.toml；
  • vercel.json；
  • CNAME。

配置按当前平台最小化添加。

一次只加当前平台需要的配置。

3.3 Deploy now

用户明确授权部署，并且当前环境有登录、CLI、权限、Git 远程状态。

这时才能 push、上传、创建项目等。

但是仍然要先检查 git status，确保无关改动留在本地。这个地方一定要小心。

3.4 Verify live URL

如果已经部署成功，要打开线上 URL 做检查。

检查：

  • 首页正常加载，不出现 404；
  • CSS/JS/images/fonts 正常；
  • 主导航能点；
  • 代表性子页能打开；
  • 移动端可用；
  • console 没有明显错误；
  • GitHub Pages 子路径下 asset 没有错；
  • 自定义域名 HTTPS 和跳转正常。

缺少浏览器工具时，live verification 状态要标成未完成。

4. 平台选择逻辑

publish-static-site 对纯静态个人站有一个默认排序：

1. Cloudflare Pages Git integration
2. GitHub Pages with GitHub Actions
3. Netlify
4. Vercel

这个排序来自纯静态个人站的维护体验。平台当然不止这些，只是默认情况下这样比较稳。

4.1 Cloudflare Pages

适合作为默认推荐。

优点是：

  • Git 集成简单；
  • 纯静态站不需要 build command；
  • 以后 push 自动更新；
  • 也支持 Direct Upload。

如果用户有 GitHub 仓库，且想要后续持续更新，我会优先考虑 Cloudflare Pages。

设置通常是：

Framework preset: None / Static HTML
Build command: empty
Output directory: site

具体要看站点目录。

4.2 GitHub Pages

适合用户想全部留在 GitHub。

如果 deploy 文件就在 repo root 或 /docs，可以用 branch source。

如果 deploy 文件在 site/、dist/、out/，更推荐 GitHub Actions workflow。

因为 GitHub Pages branch source 对自定义目录支持有限，Actions 更灵活。

4.3 Netlify

Netlify 的体验也很适合静态站。

可以走 dashboard，也可以加 netlify.toml。

适合：

  • 想要简单预览；
  • 想手动上传；
  • 已经熟悉 Netlify。

4.4 Vercel

Vercel 也能部署静态站，但对于纯 HTML/CSS/JS，它排在默认推荐之后。

适合：

  • 用户已经有 Vercel 项目；
  • 未来可能转 Next.js；
  • 团队习惯 Vercel。

但对于一个无框架个人博客，继续保持无框架形态更合适。

5. Config File Policy

发布配置按需添加。

每个平台只加需要的文件：

平台配置
GitHub Pages Actions.github/workflows/pages.yml
GitHub Pages custom domaindeploy root 下 CNAME
GitHub Pages Jekyll bypassdeploy root 下 .nojekyll
Netlifynetlify.toml
Vercelvercel.json
Cloudflare Pages多数情况下 dashboard 设置够了

配置保持少而准，避免为了“看起来完整”加一堆无关文件。

这会让用户后续困惑：

我到底是部署到 Netlify 还是 Vercel？
为什么 repo 里有三个平台配置？
哪个才生效？

发布配置越少越好，准确优先。

6. Git 和远程安全

这是发布层最容易出事故的地方。

publish-static-site 明确要求：远程动作必须用户授权。

包括：

  • 创建 GitHub 仓库；
  • 添加 remote；
  • staging；
  • commit；
  • push；
  • 启用 GitHub Pages；
  • 创建 Cloudflare/Netlify/Vercel 项目；
  • 上传文件；
  • 添加环境变量；
  • 绑定域名；
  • 修改 DNS。

在 staging 或 pushing 前，要先：

git status --short

并且区分：

  • 生成站点文件；
  • 用户已有改动；
  • 私密笔记；
  • 临时文件；
  • 凭证文件。

stage 范围只包含这次发布需要的改动。

这和普通 Agent 的区别很大。普通 Agent 很容易把“发布”理解成“把当前目录全部发出去”，这太危险了。

普通 Agent 可能觉得“发布”就是把当前目录发出去。

但工程上必须非常谨慎。

因为发布动作一旦完成，内容就进入公开状态。

7. Path Strategy

发布层里还有一个老问题：路径。

很多网站在本地 HTTP root 下没问题，是因为它引用了：

<link rel="stylesheet" href="/assets/style.css">

当你在 http://127.0.0.1:8000/ 打开时，/assets/style.css 能找到。

但是如果部署到：

https://username.github.io/repo-name/

浏览器会去找：

https://username.github.io/assets/style.css

真正需要的路径其实应该落在仓库子路径下：

https://username.github.io/repo-name/assets/style.css

于是 CSS 挂掉。

所以 publish-static-site 会先修路径问题，再进入上线步骤。

如果站点是纯静态个人站，默认应该在发布前转换成 page-relative path。

只有用户明确接受 server-root-only，比如有独立 custom domain root，才可以保留 root-absolute。

8. Framework Static Output

虽然 Idea2Site 默认纯静态，但 publish-static-site 也考虑了 framework 项目的静态输出。

如果项目属于框架项目或混合项目，它应该：

  • 检查 package.json；
  • 看已有 build script；
  • 使用项目本来就有的 build command；
  • 发布最终静态 output；
  • build workflow 沿用项目已有约定；
  • deploy root 指向最终静态 output。

常见输出包括：

dist
out
build
.output/public
public

对于 Next.js，看到 out/ 时也要确认项目真的配置了 static export。

9. 一个发布流程例子

假设用户说：

帮我把 site/ 发布到 Cloudflare Pages。

一个比较稳的流程应该是：

1. 确认 site/index.html 存在
2. 跑 review-static-site
3. 确认没有路径、隐私、乱码 blocker
4. 检查 git status
5. 确认用户是否要 Git integration 还是 Direct Upload
6. 如果只是指导，给出 Cloudflare Pages 设置
7. 如果授权远程操作，按授权范围执行
8. 拿到 live URL 后浏览器验证

如果中途 review 发现：

site/.env 存在
posts/hello.html 引用 /assets/style.css

那就必须停下来修。

这种判断会出问题：

没事，部署上去应该也能用。

发布层最重要的能力就是在该停的时候停。

10. 小结

publish-static-site 的价值远超过教用户点哪个按钮。

它真正做的是把“发布”这件事工程化：

  • 确认 deploy root；
  • 确认路径策略；
  • 确认 review 通过；
  • 确认平台；
  • 确认配置；
  • 确认远程动作授权；
  • 确认线上可访问。

我觉得这一步对 Agent 建站尤其重要。

因为 Agent 很容易在“完成感”里冲动发布。

但是一个个人网站一旦发布，就可能暴露用户身份、草稿、路径、token、旧站残留。

所以发布层必须比生成层更保守。

生成可以大胆一点，发布要谨慎一点。

这就是 publish-static-site 的核心。