文档章节
托管与部署
把 Hugo 生成的 public/ 变成线上可访问的站点:三条命令行部署路线与十一个托管平台,每页都给出完整步骤、要填的变量与失败排查入口。
开始之前,你需要
- 本地站点能正常构建:
hugo退出码为 0,且public/index.html存在。 - 有一个远端去处:对象存储桶、能 SSH 登录的主机,或者一个 Git 托管平台的账号。
读完之后你能
- 说清「构建」与「部署」的分工:
hugo产出public/,部署工具只负责搬运 - 判断自己的场景该走命令行同步,还是托管平台的 Git 集成
- 在平台上填对四个关键值:构建命令、发布目录、Hugo 版本、站点地址(
baseURL) - 用一个看得见的结果确认站点真的上线,而不是只看部署日志显示成功
- 按「平台构建失败 / 构建成功但页面 404 / 构建成功但链接样式不对」三类分头排查,并找到对应入口
接着读:用 hugo deploy 部署 · 部署到 GitHub Pages · 故障排查
这一页解决什么问题
Hugo 跑完之后,站点只是本机上的一堆文件(默认在项目根目录的 public/ 下)。这一章解决的是最后一公里:怎样把这堆文件送到一台会回应 HTTP 请求的服务器或对象存储上,让别人能用浏览器打开。
「部署」听起来像一个动作,实际是四件事连在一起,任何一环填错都会表现为「打不开」:
- 构建:
hugo把content/渲染成public/; - 搬运:把
public/的内容送到远端(命令同步,或平台的构建机自动执行); - 寻址:远端用哪个域名对外服务,以及站点配置里的
baseURL是否与之一致; - 验证:用一个能看见的结果确认文件真的在远端,而不是只看日志里的「成功」。
本章页面分两类,按你的场景选一类即可:通用部署命令(本机执行命令同步产物)与托管平台集成(把源码推到 Git 仓库,平台自动构建并发布)。
读完本章你应该能够
- 说清构建与部署的分工:
hugo只负责产出public/,部署工具只负责搬运,两者互不代劳; - 判断自己的场景该走命令行同步,还是托管平台的 Git 集成;
- 在平台上填对四个关键值:构建命令、发布目录、Hugo 版本、站点地址(
baseURL); - 用一个能看见的结果确认站点真的上线了;
- 遇到失败时,按症状找到对应入口,而不是反复重跑部署。
建议阅读顺序
- 先读完本页的「部署前必须确认的四件事」——它适用于所有平台,跳过这一步正是绝大多数「部署成功但打不开」的根因。
- 只想手工上传:读用 hugo deploy 部署、用 rclone 部署、用 rsync 部署 中与你服务器匹配的一页。
- 想让平台自动构建:按你已有的账号选一页。完全没有偏好时,GitHub Pages、Cloudflare Pages、Netlify、Vercel 是中文读者最常用的四个。只想手工上传、又不想付费的,可以看 SourceHut Pages 的手工部署。
- 部署后能打开但内容不对:回到本页的域名与重定向注意事项,再到故障排查按现象查。
从本地 public/ 到线上可访问:三种路线
无论选哪条路线,产物、变量与验证点是同一套,区别只在「谁执行构建」:
| 路线 | 你在本机执行 | 远端执行 | 适合 |
|---|---|---|---|
| 命令行同步 | hugo + 部署命令(hugo deploy、rclone sync、rsync) |
只接收文件 | 已有服务器或对象存储;想控制每次发布的时机 |
| 平台 Git 集成 | git push |
平台装工具链、构建、发布 | 没有服务器;希望每次提交自动上线 |
| 平台 Git 集成 + CI 工作流 | git push |
GitHub Actions、GitLab CI、Forgejo Actions 构建后交给 Pages | 需要自定义工具版本、图片处理或压缩 |
三条路线共用的关键值只有四个,任何平台页面都在教你填这四个:
| 关键值 | 常见取值 | 填错的表现 |
|---|---|---|
| 构建命令 | hugo 或 hugo build --gc --minify |
平台报「构建脚本退出码 1」,或产物目录为空 |
| 发布目录 | public |
部署成功但站点 404,或首页是平台的空页 |
| Hugo 版本 | 与本地一致的版本号(例如 0.167.0) |
本地正常、线上报模板或参数不存在 |
| 站点地址 | 配置里的 baseURL |
页面能开,但 CSS、图片、站内链接指向错误地址 |
部署前必须确认的四件事
- 站点能在本地正常构建和预览。 在项目根目录执行
hugo,退出码应当是 0;构建结束打开public/index.html,应当能看到你的首页内容。这一步没过就不要动部署工具——部署工具不会替你修构建错误。参见快速开始与基本用法。 - 清楚构建命令与发布目录。 构建命令通常是
hugo(新版本也接受hugo build),发布目录默认是项目根目录下的public,其位置由配置中的publishDir决定。把你的实际值记下来,后面每个平台都要填这两项。 - 站点根地址已经设置正确。 页面里的绝对链接、站点地图(sitemap)和 RSS 都依赖
baseURL;如果打算绑定自定义域名,最好在部署前就把它改成最终地址,免得上线后再改一遍。判断方法:构建后搜索public/index.html,里面出现的绝对地址应当是你期望的域名。 - 知道构建产物会出现在哪里。 托管平台的「输出目录」「artifacts」「publish directory」一类设置,指的就是这个目录。填了源码目录(
content/、仓库根目录)而不是发布目录,是新手最常见的 404 来源。
本章每页都会回答的三个问题
平台页面结构一致,照这三段读即可:
| 段落 | 内容 | 你应当得到什么 |
|---|---|---|
从本地 public/ 到线上可访问 |
完整步骤与顺序 | 一条能照着做完的路径,知道每步在干什么 |
| 你要填的变量 | 变量名、填什么、在哪填 | 一张可以边填边核对的值清单 |
| 失败时的典型报错 | 症状 → 真因 → 怎么修 | 出错时不用从头重读,直接按现象查 |
常见坑(跨平台通用)
| 症状 | 真因 | 怎么修 |
|---|---|---|
| 平台日志显示部署成功,打开网址却是 404 或平台默认页 | 发布目录填成了仓库根目录或 content/ |
改成 public;平台页面里的「发布目录」一节写了该平台的具体叫法 |
| 页面能打开,但样式、图片全丢,链接指向奇怪的域名 | baseURL 还是本地地址或临时域名 |
把 baseURL 改成最终访问地址后重新部署;用域名与重定向注意事项逐条核对 |
| 本地构建正常,平台报模板或参数不存在 | 平台的 Hugo 版本比本地旧 | 在平台配置里显式指定 HUGO_VERSION,与本地 hugo version 的输出保持一致 |
平台构建报 command not found: hugo |
平台镜像里没有 Hugo,或版本声明写在平台读不到的位置 | 按对应平台页把版本变量写进配置文件(netlify.toml、amplify.yml、工作流 env 等) |
| 部署成功,但几分钟内看到的还是旧页面 | CDN 或浏览器缓存 | 强制刷新;确认平台的缓存与失效设置,见本页「缓存」一条 |
站点在子路径(例如 https://user.github.io/repo/)下链接全错 |
baseURL 少了子路径,或模板里硬编码了以 / 开头的绝对地址 |
让平台把完整地址传给构建(GitHub Pages 的 --baseURL、GitLab 的 CI_PAGES_URL 都是这个用途) |
分诊与更系统的排查方法见故障排查;部署前想先自查一遍站点,可以跑审计。
关于构建产物
Hugo 每次构建都会重新生成发布目录,因此:
托管平台只需要「源码加构建命令」,不需要你提交构建结果;把产物一起提交反而容易让仓库里留下过期文件,掩盖真正的构建问题。
域名与重定向注意事项
- 自定义域名:临时域名只在测试阶段有意义。绑定自定义域名后,记得把
baseURL(或平台传给构建的等价变量)改成该域名并重新部署,否则页面内的绝对链接仍指向临时地址。 - 404 页面:静态托管平台一般提供自定义 404 的入口。在
layouts/中定义 404 模板,构建后会得到public/404.html,再在平台侧把它设为错误页。 - 重定向与尾斜杠:Hugo 默认输出以
/结尾的 URL。如果平台强制去除尾斜杠或做大小写归一化,可能出现重定向循环或 404。上线后建议抽查几个页面。 - 缓存:静态资源的缓存策略由平台控制,重新部署不等于所有访客立刻拿到新文件。更新样式或图片后要留意旧缓存的影响。
本章内容
- 用 hugo deploy 部署 把本地 public/ 同步到 S3、Azure Blob Storage 或 Google Cloud Storage:配置部署目标、空跑确认、正式上传,以及报错时的排查入口。 (今天)
- 用 rclone 部署 用 rclone 把 public/ 同步到支持 SFTP、S3 等协议的任意主机:连接参数、远端配置、验证方法与误删排查。 (今天)
- 用 rsync 部署 用 rsync 把 public/ 同步到 SSH 主机:配置免密登录、写一个可重复执行的 deploy 脚本,以及权限、误删、行尾等常见故障。 (今天)
- 部署到 AWS Amplify 把 GitHub 仓库接到 AWS Amplify 持续部署:写 amplify.yml、填对工具版本与发布目录、确认站点上线,以及构建失败时的排查入口。 (今天)
- 部署到 Azure Static Web Apps 用 GitHub Actions 把 Hugo 站点部署到 Azure Static Web Apps:部署令牌、工作流、发布目录、404 重写,以及失败时的排查入口。 (今天)
- 部署到 Cloudflare Pages 用 Wrangler 把 Hugo 站点部署到 Cloudflare:wrangler.jsonc、构建脚本、构建缓存与定时重建,附构建失败与 404 的排查入口。 (今天)
- 部署到 Codeberg Pages 用 Forgejo Actions 把 Hugo 站点发布到 Codeberg Pages:工作流、HUGO_BASEURL 的三种站点形态、runner 选择与常见失败排查。 (今天)
- 部署到 Firebase 用 GitHub Actions 把 Hugo 站点部署到 Firebase Hosting:服务账号密钥、工作流、Project ID 与 baseURL,附认证失败的排查入口。 (今天)
- 部署到 GitHub Pages 用 GitHub Actions 把 Hugo 站点持续部署到 GitHub Pages:发布源设置、工作流、子路径与 baseURL,附权限与 404 的排查入口。 (今天)
- 部署到 GitLab Pages 用 GitLab CI 把 Hugo 站点持续部署到 GitLab Pages:.gitlab-ci.yml、build.sh、baseURL 与压缩产物,附流水线失败的排查入口。 (今天)
- 部署到 Netlify 用 Netlify 的 Git 集成持续部署 Hugo 站点:netlify.toml、构建命令与发布目录、Dart Sass 变体,附构建失败的排查入口。 (今天)
- 部署到 Render 用 Render Blueprint 持续部署 Hugo 静态站点:render.yaml、build.sh、发布目录与工具版本,附构建失败的排查入口。 (今天)
- 部署到 SourceHut Pages 用手工上传或 SourceHut 构建系统发布 Hugo 站点:hut 命令、.build.yml 构建清单、baseURL 与失败排查。 (今天)
- 部署到 Vercel 用 Vercel 的 Git 集成持续部署 Hugo 静态站点:vercel.json、build.sh、输出目录与工具版本,附构建失败的排查入口。 (今天)