发布静态网站
目标
发布或准备好部署一个已完成的静态网站。
此技能适用于可部署的 HTML/CSS/JS 输出,例如 site/、dist/、out/、public/ 或 docs/。它也可以用于发布那些在生成静态输出文件夹后的框架项目,但不应仅仅为了部署而将一个纯静态网站转换为框架项目。
默认原则:
- 优先选择简单的静态托管,而非特定框架的部署。
- 对用户会继续编辑的站点,优先选择基于 Git 的部署。
- 仅一次性快速发布时,才优先考虑直接上传。
- 除非用户明确要求,否则不创建远程仓库、不推送代码、不更改 DNS、不添加域名,也不部署到付费账户。
契约
输入:
- 静态部署根目录,例如
site/、dist/、out/、public/、docs/或仓库根目录。 - 首选平台或目标:GitHub Pages、Cloudflare Pages、Netlify、Vercel、自定义域名、仅提供指导或执行直接部署。
- 当前的 Git/仓库状态、平台账户访问权限、CLI/浏览器登录状态以及任何部署限制。
输出:
- 具体的部署设置:平台、分支、构建命令、基目录、发布/输出目录,以及必要的配置文件。
- 可选的平台特定配置,例如 GitHub Pages 工作流、
netlify.toml、vercel.json、.nojekyll或CNAME。 - 实际执行部署时的线上 URL 和部署后验证结果。
- 当缺少凭据或账户访问权限时,手动仪表板操作步骤。
边界:
- 不构建或重新设计网站;将缺陷路由到合适的子技能。
- 除非得到明确授权,否则不推送、不创建仓库/项目、不上传、不绑定域名、不更改 DNS,也不使用付费资源。
- 不要将部署用作解决本地/静态路径兼容性问题的变通方法,除非用户明确接受了仅服务器根目录的行为。
成功门:
review-static-site已通过,或者未解决的风险已明确说明。- 部署根目录包含
index.html,并且平台将发布正确的文件夹。 - 部署后线上 URL 能加载主页、资源、导航以及有代表性的子页面。
如果门未通过:
- 在部署前修复路径、资源、编码或页面类型方面的阻塞问题。
- 将内容/设计/导入问题路由到
personalize-site、edit-site-part、add-blog-posts、make-personal-site或copy-website-style。 - 重新运行
review-static-site,然后重试或更新部署设置。
参考
仅加载所选平台或问题所需的参考:
- 路径策略和直接打开兼容性:
references/path-strategy.md。 - Cloudflare Pages Git 集成和直接上传:
references/cloudflare-pages.md。 - GitHub Pages 分支源和 Actions 工作流:
references/github-pages.md。 - Netlify 仪表板和
netlify.toml:references/netlify.md。 - Vercel 仪表板和
vercel.json:references/vercel.md。
官方文档:
- GitHub Pages 发布源:https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- GitHub Pages 自定义工作流:https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
- Cloudflare Pages 静态 HTML:https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
- Cloudflare Pages Git 集成:https://developers.cloudflare.com/pages/get-started/git-integration/
- Cloudflare Pages 直接上传:https://developers.cloudflare.com/pages/get-started/direct-upload/
- Netlify 创建部署:https://docs.netlify.com/deploy/create-deploys/
- Netlify 构建配置:https://docs.netlify.com/build/configure-builds/overview/
- Vercel 部署:https://vercel.com/docs/deployments
- Vercel 项目配置:https://vercel.com/docs/project-configuration
部署模式
首先确定用户的实际需求:
- 仅指导:解释平台选择和具体设置。除非有用,否则不编辑文件。
- 准备仓库:添加所需的配置文件,并告知用户需要在托管仪表板中点击什么。
- 立即部署:仅当用户明确要求并且存在所需的 CLI/认证/会话时才执行远程操作。
- 验证线上 URL:在浏览器中打开已部署的 URL,并与本地网站进行比对。
如果缺少凭据、账户访问权限、浏览器登录或 CLI 认证,则提供确切的仪表板步骤,而不是编造变通方法。
工作流程
- 确定静态输出文件夹以及用户的首选平台(如果有)。
- 在发布前调用或建议使用
review-static-site。 - 确认部署根目录包含
index.html。 - 在发布前检查资源路径,并转换意外的根绝对站点本地路径。当路径行为不明确时,加载
references/path-strategy.md。 - 选择最简单的匹配平台和部署模式。
- 加载所选平台的参考,并仅添加该平台所需的配置文件。
- 如果通过 Git 部署,检查 Git 状态,避免包含无关或私有文件。
- 如果用户授权了远程操作,则推送或部署已约定的内容。
- 发布后,在浏览器中打开线上 URL 并验证部署的网站。
预检清单
在编写部署配置或告知用户设置之前,请执行以下检查:
- 部署根目录:选择直接包含
index.html的文件夹。 - 入口页面:
index.html必须存在于部署根目录的顶层。 - 直接打开预览:根目录的
index.html在直接从文件系统打开时,应能保持 CSS、JS、图片和导航的功能,除非用户明确接受了仅服务器行为。 - 本地 HTTP:使用
python -m http.server提供部署根目录的服务,并确认其在http://127.0.0.1:<port>/下正常工作。 - 静态审计:运行或推荐
review-static-site检查链接、UTF-8 可读性、占位残留、浏览器渲染、隐私残留和移动端布局。 - 资源路径:检查
href、src、srcset、CSS 中的url(...)、字体、favicon、封面图片、RSS、站点地图和清单链接。 - 私有数据:确保令牌、本地文件系统路径、草稿笔记、来源站点身份和个人秘密不会被发布。
- 输出完整性:确认子页面、文章、图片、供应商字体、KaTeX/数学资源以及复制的媒体文件都在部署根目录内。
将这些视为阻塞问题:
- 部署根目录中没有
index.html。 - 本地 CSS、JS、图片、字体、RSS、站点地图或供应商资源路径损坏。
- 源文件包含乱码或不可读的编码。
- 生成的个人网站仍包含应被替换的复制来源身份。
- 生成的纯静态网站中仍然存在意外的根绝对站点本地路径,例如
/assets/...、/posts/...、/data/...或/images/...。 - 网站仅通过本地 HTTP 工作,因为根绝对路径正从
127.0.0.1提供,但直接文件打开或子路径部署将丢失 CSS/JS/图片。 - 会部署隐私敏感的文件或密钥。
- 平台将部署错误的文件夹。
平台选择
纯静态个人网站的默认排名:
- Cloudflare Pages Git 集成:对于生成的
site/文件夹和未来更新,最好的默认选择。 - 带 GitHub Actions 的 GitHub Pages:当用户希望将所有内容保留在 GitHub 内时最佳。
- Netlify:简单的静态托管,具有友好的预览和仪表板设置。
- Vercel:当用户已经在使用 Vercel 或将来可能迁移到 Next.js 时是一个好选择,但纯 HTML 时非默认。
决策规则:
- 如果用户希望最小化摩擦并且拥有 GitHub 仓库:Cloudflare Pages Git 集成。加载
references/cloudflare-pages.md。 - 如果用户希望仅使用 GitHub 托管:GitHub Pages。加载
references/github-pages.md。 - 如果部署文件位于仓库根目录或
/docs:GitHub Pages 分支源是可接受的。 - 如果部署文件位于
site/、dist/、out/或其他自定义文件夹:推荐使用 GitHub Actions 进行 GitHub Pages 部署。 - 如果用户今天想手动上传:Cloudflare 直接上传或 Netlify 手动部署。
- 如果用户已有 Vercel 账户/项目:使用 Vercel 并明确设置输出目录。
框架静态输出
如果网站不是纯 HTML/CSS/JS:
- 检查
package.json、框架配置和现有脚本。 - 使用项目现有的构建命令;不要发明 npm 工作流。
- 发布最终的静态输出文件夹,而不是源文件夹。
- 常见输出包括
dist、out、build、.output/public和public,具体取决于框架。 - 对于 Next.js 静态导出,在将
out/视为最终输出之前,验证项目是否确实配置为静态导出。 - 对于 Vue/Vite/Astro 风格的项目,在成功构建后发布配置的输出目录。
如果用户要求纯静态发布且不存在框架文件,则不要引入 npm。
配置文件策略
仅添加与所选平台匹配的配置文件:
- GitHub Pages Actions:
.github/workflows/pages.yml。 - GitHub Pages 自定义域名:部署根目录中的
CNAME,仅当用户提供了域名时。 - GitHub Pages Jekyll 绕过:部署根目录中的
.nojekyll,当有需要时。 - Netlify:仅当仪表板设置不足或用户希望在 Git 中保存配置时,才添加
netlify.toml。 - Vercel:仅当 Vercel 需要明确输出设置时,才添加
vercel.json。 - Cloudflare Pages:对于纯静态网站,通常仪表板设置就足够了。
不要为每个平台同时添加部署配置。
Git 与远程安全
在任何远程操作之前,说明将要进行的操作并确认用户已要求执行:
- 创建 GitHub 仓库。
- 添加远程仓库。
- 暂存或提交文件。
- 将提交推送到远程分支。
- 启用 GitHub Pages。
- 创建 Cloudflare、Netlify 或 Vercel 项目。
- 上传文件到托管提供商。
- 添加环境变量。
- 添加自定义域名或更改 DNS 记录。
在暂存或推送之前:
- 运行
git status --short。 - 区分生成的站点文件与无关的用户更改。
- 不要暂存无关的更改。
- 不要发布私人笔记、凭据、本地路径、包含密钥的截图或临时文件。
切勿将密钥、令牌、私人笔记或本地文件系统路径放入静态网站或部署配置中。
部署后验证
在平台报告线上 URL 后:
- 使用实际可用的交互式浏览器工具打开已部署的 URL。“可用”意味着它已暴露在当前轮次的可调用工具列表中。在 Codex 中,当路由到该轮次时,这可能是浏览器/应用内浏览器插件。
- 验证首页不是 404 页面、空白页或目录列表。
- 验证 CSS、JavaScript、图片、字体、favicon、RSS、站点地图和供应商资源是否从已部署的域名加载。
- 点击主导航,以及每种页面类型至少一个有代表性的子页面。
- 测试桌面端和移动端宽度。
- 检查浏览器控制台是否有缺失资源或 JavaScript 错误。
- 确认元数据、标题、描述、Open Graph 图片、规范 URL、RSS、站点地图和 robots 文件(如果存在)。
- 如果使用 GitHub 项目 Pages,请特别检查仓库子路径下的子页面和资源 URL。
- 如果使用自定义域名,验证 HTTPS 以及根域名和
www之间的重定向(如果已配置)。
如果没有可调用的交互式浏览器工具,则不要假装进行了实时的浏览器验证。如果实时视觉验证很重要,请要求用户启用或调用浏览器工具;对于 Codex,这可能意味着发送一个明确提及 @browser 的请求。如果用户没有重新路由或客户端没有这样的工具,则回退到 Playwright、截图、HTTP 检查或静态检查,并说明限制。
当实际可以调用交互式浏览器工具时,不要默认使用 Playwright 或仅截图方式的实时验证。仅将 Playwright 用作回退,或者当用户明确要求脚本化的部署检查时使用。
如果部署的网站与本地预览不同,请在更改设计代码之前检查部署日志、输出目录和资源路径策略。
输出
保持最终面向用户的报告简洁:
- 所选平台及其原因。
- 发布或准备的静态文件夹。
- 部署模式:指导、已准备配置、Git 集成、直接上传或实时部署。
- 使用的设置:分支、构建命令、基目录、发布/输出目录。
- 更改的配置文件(如果有)。
- 所选平台的官方指南 URL。
- 线上 URL(如果已部署)。
- 执行的验证以及任何剩余的手动步骤。
如果仅请求了指导,则不要假装网站已部署。给出具体的平台设置和官方指南链接。