Hugo 中文文档 · 社区翻译

文档章节

托管与部署

把 Hugo 站点发布到托管平台或对象存储的部署指南。

本章内容

Hugo 生成的是纯静态文件，所以「部署」本质上就是把构建产物送到一台会回应 HTTP 请求的服务器或对象存储上。本部分从两个角度介绍这件事。

第一条线是通用部署命令。 站点构建完成后，用命令行工具把发布目录同步到远端：

第二条线是托管平台集成。 把站点源码放进 Git 仓库，由平台在每次推送时自动构建并发布，本地不必执行部署命令：

部署之前

无论选哪种方式，先确认下面几件事：

  1. 站点能在本地正常构建和预览，参见快速开始与基本用法。
  2. 清楚构建命令与发布目录。构建命令通常是 hugo build，发布目录默认是项目根目录下的 public，其位置由配置中的 publishDir 决定。
  3. 站点根地址已经设置正确。页面里的绝对链接、站点地图和 RSS 都依赖 baseURL；如果打算绑定自定义域名，最好在部署前就把它改成最终地址，免得上线后再改一遍。
  4. 知道构建产物会出现在哪里。托管平台的「输出目录」「artifacts」一类设置，指的就是这个目录。

关于构建产物

Hugo 每次构建都会重新生成发布目录，因此：

注意： 不要把发布目录（public）的内容提交到 Git 仓库，Hugo 会在下次构建时重新创建它。正确做法是在 .gitignore 中忽略它，只提交源码与配置文件。

托管平台只需要「源码加构建命令」，不需要你提交构建结果；把产物一起提交反而容易让仓库里留下过期文件，掩盖真正的构建问题。

各平台页面的共同结构

托管平台的界面和术语各不相同，但每个平台页面的组织方式是一致的：

  • 前置条件：需要哪些账号、仓库，以及本地要先完成什么。
  • 仓库与配置：把平台要求的配置文件（构建脚本、工作流文件）放到正确路径下，然后提交推送。
  • 构建命令与输出目录：平台执行什么命令、从哪里取走产物。多数平台直接用 public 作为输出目录。
  • 域名与重定向：首次部署后会拿到一个临时域名；绑定自定义域名、处理 404 与重定向通常需要额外设置。

域名与重定向注意事项

  • 自定义域名：临时域名只在测试阶段有意义。绑定自定义域名后，记得把 baseURL 改成该域名并重新部署，否则页面内的绝对链接仍指向临时地址。
  • 404 页面：静态托管平台一般提供自定义 404 的入口。在 layouts/ 中定义 404 模板，构建后会得到 public/404.html，再在平台侧把它设为错误页。
  • 重定向与尾斜杠：Hugo 默认输出以 / 结尾的 URL。如果平台强制去除尾斜杠或做大小写归一化，可能出现重定向循环或 404。上线后建议抽查几个页面。
  • 缓存：静态资源的缓存策略由平台控制，重新部署不等于所有访客立刻拿到新文件。更新样式或图片后要留意旧缓存的影响。

本章内容

  • 用 hugo deploy 部署 用 hugo deploy 把站点同步到对象存储的完整步骤。 （今天）
  • 用 rclone 部署 用 rclone 把 Hugo 构建产物同步到远端主机。 （今天）
  • 用 rsync 部署 用 rsync 把 Hugo 构建产物同步到 SSH 主机并脚本化。 （今天）
  • 部署到 AWS Amplify 在 AWS Amplify 上托管 Hugo 站点并持续部署。 （今天）
  • 部署到 Azure Static Web Apps 在 Azure Static Web Apps 上托管 Hugo 站点。 （今天）
  • 部署到 Cloudflare Pages 在 Cloudflare 上托管 Hugo 站点并定时重建。 （今天）
  • 部署到 Codeberg Pages 在 Codeberg Pages 上托管 Hugo 站点。 （今天）
  • 部署到 Firebase 用 GitHub Actions 把 Hugo 站点持续部署到 Firebase Hosting。 （今天）
  • 部署到 GitHub Pages 用 GitHub Actions 把 Hugo 站点持续部署到 GitHub Pages。 （今天）
  • 部署到 GitLab Pages 用 GitLab CI 把 Hugo 站点持续部署到 GitLab Pages。 （今天）
  • 部署到 Netlify 用 Netlify 的 Git 集成持续部署 Hugo 站点。 （今天）
  • 部署到 Render 用 Render Blueprint 持续部署 Hugo 静态站点。 （今天）
  • 部署到 SourceHut Pages 用手工上传或 SourceHut 构建系统发布 Hugo 站点。 （今天）
  • 部署到 Vercel 用 Vercel 的 Git 集成持续部署 Hugo 静态站点。 （今天）