用 hugo deploy 部署
把本地 public/ 同步到 S3、Azure Blob Storage 或 Google Cloud Storage:配置部署目标、空跑确认、正式上传,以及报错时的排查入口。
开始之前,你需要
- 本地
hugo能构建成功,public/里有内容 - 一个对象存储账号(AWS、Azure 或 Google Cloud)与已创建的存储桶
- 会在命令行里配置云服务凭据(
aws configure、az login或gcloud auth login)
读完之后你能
- 在项目配置里写出一个可用的
[[deployment.targets]],并说清name与url各自的作用 - 先用
--dryRun看清将要上传与删除的文件,再执行正式部署 - 用
--maxDeletes、include、exclude避免误删远端文件 - 部署后在浏览器里确认站点可访问,并判断 403、404、旧页面分别该查哪里
接着读:用 rclone 部署 · 用 rsync 部署 · 部署目标配置 · hugo deploy
hugo deploy 命令可以把你的站点部署到 Amazon S3、Azure Blob Storage 或 Google Cloud Storage。
这一页解决什么问题
hugo 构建完之后,产物只在本机。这一页解决的是把 public/ 送到对象存储、并让它对外可访问:写一个部署目标、先空跑看清楚 Hugo 打算改什么、再真正上传。
它适合「已经有一个存储桶,只想把文件同步上去」的场景。与另外两条路线相比:
- 用
hugo deploy:Hugo 自己比对本地与远端(文件名、大小、MD5),只上传变化的部分,并按匹配器设置远端文件头(例如缓存控制); - 别用它做代码部署或需要执行远端脚本的发布——它只搬文件;需要 SFTP/任意主机时用 rclone 或 rsync;
- 别用它替代构建——
hugo deploy不会替你运行hugo,上传的是已经生成的产物。
从本地 public/ 到线上可访问
按顺序走完这六步,每一步都给出「你应当看到什么」:
| 步骤 | 你做什么 | 你应当看到什么 |
|---|---|---|
| 1 | 在项目根目录执行 hugo |
退出码 0;public/index.html 存在且是你期望的首页内容 |
| 2 | 在配置文件中写入 [[deployment.targets]](本页下文) |
配置文件保存后,hugo deploy 不再提示找不到目标 |
| 3 | 配置云凭据(aws configure / az login / gcloud auth login) |
对应 CLI 自己的一条读取命令能列出你的存储桶 |
| 4 | 执行 hugo deploy --dryRun |
终端列出「将上传」「将删除」的文件清单,且不做任何改动 |
| 5 | 核对清单后执行 hugo deploy |
终端逐行显示上传/删除结果,最后没有 error 级别的输出 |
| 6 | 打开存储桶的静态网站地址(或你绑定的自定义域名) | 首页正常显示,样式与图片都在;抽查一个子页面也正常 |
这里最容易漏的是第 4 步。删除是不可逆的:本地 public/ 里已经不存在的文件,远端会被删除。先用 --dryRun 看清清单,是这条路线唯一的安全网。
前提条件
-
已经完成快速开始,或者已经有一个准备部署上线的 Hugo 站点。
-
拥有要部署到的服务商账号:AWS、Azure 或 Google Cloud。
-
已经完成身份认证:
- AWS:安装 CLI 后执行
aws configure。 - Azure:安装 CLI 后执行
az login。 - Google Cloud:安装 SDK 后执行
gcloud auth login。
三种服务都支持多种认证方式,包括通过环境变量提供凭据,详见 gocloud.dev 说明。
- AWS:安装 CLI 后执行
-
已经创建用于部署的存储桶(bucket)。如果希望站点对外公开,还要把存储桶配置为可公开读取的静态网站。
配置部署目标
在项目配置文件中创建部署目标。必填参数只有名称 name 和地址 url:
[deployment]
[[deployment.targets]]
name = 'production'
url = 's3://my_bucket?region=us-west-1'两个字段的分工:
name:给这个目标起的名字,hugo deploy --target=<target name>用它来选择目标;url:远端位置。方案前缀决定服务商(s3://、azblob://、gs://等),查询串里可以带服务商参数(上面例子里的region)。
你要填的变量
| 变量 | 填什么 | 在哪填 |
|---|---|---|
name |
目标名,例如 production、staging |
项目配置文件的 [[deployment.targets]] 下 |
url |
存储桶地址,含方案前缀与必要的服务商参数 | 同上 |
| 云凭据 | 访问密钥、账号登录态或服务账号 | 云服务 CLI(aws configure、az login、gcloud auth login)或环境变量 |
| 站点地址 | 最终对外地址,即配置里的 baseURL |
项目配置文件;绑定自定义域名后必须同步修改 |
执行部署
向某个目标部署:
hugo deploy [--target=<target name>]该命令会把本地发布目录(默认是 public)的内容与目标存储桶同步。不指定目标时,Hugo 部署到配置中的第一个目标。
更多命令行选项见 hugo help deploy 或命令文档。
生成文件清单
hugo deploy 会遍历本地发布目录和远端存储桶,各自生成一份文件清单。哪些文件纳入、哪些排除,由部署目标的配置决定:
include:默认跳过所有文件,只保留匹配该模式的文件。exclude:跳过匹配该模式的文件。
比较文件清单
Hugo 会比较本地与远端两份清单,确定需要做哪些改动。它先比较文件名;如果两边都存在,再比较文件大小和 MD5 校验和。任何差异都会触发重新上传,而远端存在、本地已不存在的文件会被删除。
--force 标志会强制重新上传所有文件,即使 Hugo 没有发现本地与远端的差异。
--confirm 或 --dryRun 标志会让 Hugo 先显示检测到的差异,然后暂停或直接停止。
两个标志的差别值得记住:--dryRun 只显示、不执行,也不会等你按键;--confirm 会显示清单后停下来等你确认,适合真正要动手但想再看一眼的时候。
同步
最后,Hugo 把变更应用到远端存储桶:上传缺失或已变化的文件,删除本地已不存在的远端文件。上传文件的头部信息会依据匹配器(matchers)配置在远端设置。
验证:部署后你应当看到什么
别只看终端的成功提示,按下面两级确认:
- 远端确实有文件:用云服务 CLI 列一遍桶里的对象(例如
aws s3 ls s3://my_bucket/ --recursive),应当看到index.html、404.html、sitemap.xml与你内容目录对应的子目录。 - 浏览器确实能访问:打开桶的静态网站地址或自定义域名。首页、一篇内页、一张图片各点开一次;图片能显示说明相对路径与
baseURL都对得上。
如果第 1 步有文件、第 2 步打不开,问题在访问策略(桶策略、静态网站托管开关、CDN),不在 Hugo。
失败时:典型报错与排查入口
| 症状 | 真因 | 怎么修 |
|---|---|---|
报错形如 unknown command "deploy" for "hugo" |
装的是不含 deploy 功能的 Hugo 版本 | 换成 deploy 或 extended/deploy 版本,见安装 Hugo;用 hugo version 确认 |
| 认证失败:报错里出现凭据相关的字样,或提示找不到默认凭据 | 凭据没配、配置在另一个终端环境、或环境变量没生效 | 重新执行 aws configure / az login / gcloud auth login,然后用对应 CLI 的一条读取命令验证凭据可用 |
上传时报权限类错误(AccessDenied、403 等) |
凭据有权登录但无权写这个桶 | 检查账号对该桶的写权限;桶策略与 IAM 规则属于服务商侧,链接见本页「前提条件」 |
| 站点能打开首页,子页面或图片 404 | 上传的目标路径与静态网站托管的根路径不一致 | 用 CLI 列出远端对象,核对 index.html 是否在托管的根下;必要时调整 url 的路径部分 |
| 浏览器 403,但文件确实上传了 | 桶没有开放匿名读取,或静态网站托管没开启 | 回到「前提条件」第 4 步,按服务商文档配置公开读取 |
| 终端显示删除了一大批远端文件 | 本地 public/ 是空的或不完整(例如构建失败后仍然部署),或 include/exclude 写错 |
立即停止后续部署;用 --dryRun 复现清单,检查 include/exclude;删除上限由 --maxDeletes 控制(默认 256),它是保护而不是修复 |
| 部署成功,但打开还是旧页面 | CDN 缓存或浏览器缓存 | 等待失效、强制刷新;实测 v0.167.0:--invalidateCDN 默认为 true(hugo deploy --help 输出 --invalidateCDN ... (default true)),即默认会通知部署目标里配置的 CDN 失效;匹配器等设置在部署配置里 |
--dryRun 是这一页最有用的排查工具:它把 Hugo 的完整计划打印出来,且不改动任何远端文件。看不明白结果时,先把 --dryRun 的输出保存下来逐行读。
进阶配置
匹配器、缓存控制等进阶选项,见配置部署;完整命令行选项见 hugo deploy。