部署到 AWS Amplify
把 GitHub 仓库接到 AWS Amplify 持续部署:写 amplify.yml、填对工具版本与发布目录、确认站点上线,以及构建失败时的排查入口。
开始之前,你需要
- 一个 AWS 账号与一个 GitHub 账号,项目已推送到 GitHub 仓库
- 本地
hugo能构建成功,知道自己的 Hugo 版本(hugo version) - 仓库根目录可以新增文件(
amplify.yml)并提交推送
读完之后你能
- 在仓库根目录写出可用的
amplify.yml,让 Amplify 在构建机上装好 Hugo 并构建站点 - 说清
HUGO_VERSION、HUGO_CACHEDIR、artifacts.baseDirectory三个值各自控制什么 - 在 Amplify 控制台完成从仓库到线上站点的全流程,并找到已发布网址
- 构建失败或页面 404 时,按日志定位是版本、路径还是
baseURL的问题
接着读:部署到 Azure Static Web Apps · 部署到 Cloudflare Pages · 缓存配置 · 故障排查
下面这些步骤用于实现从 GitHub 仓库持续部署。其他 Git 服务商(例如 GitLab、Bitbucket)的总体流程相同。
这一页解决什么问题
本地 public/ 已经能生成,现在要让它变成一个人人可访问的网址,而且以后每次 git push 都自动更新。这一页给出的就是这条路径:仓库里写一个 amplify.yml → 在控制台把仓库接进来 → 等构建完成 → 拿到网址。
分工要说清楚:构建在 AWS 的机器上发生,不在你的电脑上。所以「本地能构建」不等于「线上能构建」——线上缺少的 Hugo、Dart Sass、Go、Node.js,都要由 amplify.yml 现装。这也是最常见的失败来源。
从本地 public/ 到线上可访问
| 阶段 | 你做什么 | 完成后如何验证 |
|---|---|---|
| 1. 本地确认 | 在项目根目录执行 hugo |
退出码 0,public/index.html 是期望内容 |
| 2. 写构建配置 | 在仓库根目录创建 amplify.yml(第 1 步) |
文件与 hugo.toml 同级;git status 能看到它是新增文件 |
| 3. 配置缓存 | 在项目配置中设置 [caches.images](第 2 步) |
配置保存后本地再跑一次 hugo 仍成功 |
| 4. 推送 | git add -A && git commit && git push(第 3 步) |
GitHub 仓库页面上能看到这两个文件 |
| 5. 接入 Amplify | 控制台创建应用并选择仓库与分支(第 4–9 步) | 「App settings」页面出现后,说明仓库已连上 |
| 6. 部署 | 确认后按 Save and deploy(第 10–11 步) | Amplify 页面进入构建进度,日志里能看到 Installing Hugo 与 hugo version 输出 |
| 7. 访问 | 按 Visit deployed URL(第 12 步) | 首页正常显示,样式与图片都在 |
你要填的变量
| 变量 | 在哪填 | 填什么 | 填错的后果 |
|---|---|---|---|
HUGO_VERSION |
amplify.yml 的 env.variables |
与本地一致的版本,例如 0.167.0 |
构建机上装到你没测过的版本,可能报模板或参数不存在 |
DART_SASS_VERSION |
同上 | 需要 Sass 时填,例如 1.105.0 |
站点用了 Sass 时构建报找不到 sass |
GO_VERSION / NODE_VERSION |
同上 | 站点用了 Hugo Modules / npm 依赖时才需要 | 用到 go.mod 或 package-lock.json 时构建失败 |
TZ |
同上 | 构建时区,例如 Europe/Oslo |
date 相关的输出与预期差几个小时 |
HUGO_CACHEDIR |
同上 | 缓存目录路径,需与 cache.paths 一致 |
缓存不生效,每次构建都重新处理图片 |
artifacts.baseDirectory |
amplify.yml 的 artifacts |
public |
部署成功但网址 404 |
baseURL |
项目配置文件 | 最终访问地址 | 页面能打开但样式、站内链接指向错误地址 |
前提条件
继续之前,请先完成以下任务:
- 创建一个 AWS 账号。
- 登录你的 AWS 账号。
- 创建一个 GitHub 账号。
- 登录你的 GitHub 账号。
- 为你的项目创建一个 GitHub 仓库。
- 为项目创建一个本地 Git 仓库,并添加指向该 GitHub 仓库的远端(remote)引用。
- 在本地 Git 仓库中创建 Hugo 项目,并用
hugo server命令测试它。 - 把改动提交到本地 Git 仓库,并推送到 GitHub 仓库。
操作步骤
第 1 步:创建 amplify.yml
在项目根目录下创建 amplify.yml 文件,按需要调整工具版本和时区。HUGO_VERSION 等变量的值要与站点实际需要的版本一致:
version: 1
env:
variables:
# 定义工具版本
DART_SASS_VERSION: 1.105.0
GO_VERSION: 1.27.1
HUGO_VERSION: 0.167.0
NODE_VERSION: 24.21.0
# 设置构建时区
TZ: Europe/Oslo
# 设置构建缓存目录
HUGO_CACHEDIR: ${PWD}/.cache/hugo
frontend:
phases:
preBuild:
commands:
# 创建用于下载的临时目录
- build_temp_dir=$(mktemp -d)
# 创建本地工具目录
- mkdir -p "${HOME}/.local"
# 安装 Dart Sass
- |
echo "Installing Dart Sass ${DART_SASS_VERSION}..."
curl -sfL --output-dir "${build_temp_dir}" -O "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
tar -C "${HOME}/.local" -xf "${build_temp_dir}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
export PATH="${HOME}/.local/dart-sass:${PATH}"
# 安装 Go
- |
if [[ -f "go.mod" ]]; then
echo "Installing Go ${GO_VERSION}..."
curl -sfL --output-dir "${build_temp_dir}" -O "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
tar -C "${HOME}/.local" -xf "${build_temp_dir}/go${GO_VERSION}.linux-amd64.tar.gz"
export PATH="${HOME}/.local/go/bin:${PATH}"
fi
# 安装 Hugo
- |
echo "Installing Hugo ${HUGO_VERSION}..."
curl -sfL --output-dir "${build_temp_dir}" -O "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
mkdir -p "${HOME}/.local/hugo"
tar -C "${HOME}/.local/hugo" -xf "${build_temp_dir}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
export PATH="${HOME}/.local/hugo:${PATH}"
# 安装 Node.js
- |
if [[ -f "package-lock.json" ]]; then
echo "Installing Node.js ${NODE_VERSION}..."
curl -sfL --output-dir "${build_temp_dir}" -O "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.gz"
tar -C "${HOME}/.local" -xf "${build_temp_dir}/node-v${NODE_VERSION}-linux-x64.tar.gz"
export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
fi
# 在构建日志中打印各工具的版本,便于排查问题
- |
echo "Logging tool versions..."
command -v sass &> /dev/null && echo "Dart Sass: $(sass --version)" || echo "Dart Sass: not installed"
command -v go &> /dev/null && echo "Go: $(go version)" || echo "Go: not installed"
command -v hugo &> /dev/null && echo "Hugo: $(hugo version)" || echo "Hugo: not installed"
command -v node &> /dev/null && echo "Node.js: $(node --version)" || echo "Node.js: not installed"
# 配置 Git
- |
echo "Configuring Git..."
git config --global core.quotepath false
# 获取完整的 Git 历史
- |
if [[ $(git rev-parse --is-shallow-repository) == true ]]; then
echo "Fetching full Git history..."
git fetch --unshallow
fi
# 初始化 Git 子模块
- |
if [[ -f .gitmodules ]]; then
echo "Initializing Git submodules..."
git submodule update --init --recursive
fi
# 安装 Node.js 依赖
- |
if [[ -f package-lock.json ]]; then
echo "Installing Node.js dependencies..."
npm ci
fi
build:
commands:
# 构建项目
- |
echo "Building the project..."
hugo build --gc --minify
artifacts:
baseDirectory: public
files:
- '**/*'
cache:
paths:
- .cache/hugo/**/*你应当看到什么:把文件保存好之后,本地执行 hugo build --gc --minify 仍然成功。真正的验证在部署日志里——构建开始后,日志中会出现 Installing Hugo 0.167.0...、Hugo: hugo v0.167.0... 与 Building the project... 三处输出;只要版本号与你填的一致,就说明配置生效了。
关于 hugo build --gc --minify 这段构建命令:
hugo build是带子命令的构建写法,与本页它处的hugo等价;--gc构建后清理无用缓存,--minify压缩输出的 HTML/CSS/JS;- 脚本自己下载指定版本的 Hugo,所以实际生效的版本就是
HUGO_VERSION,与平台镜像里带的版本无关; artifacts.baseDirectory: public告诉 Amplify 从哪里取产物,这个值必须是public(或你自定义的publishDir)。
第 2 步:配置图片缓存
在本地 Git 仓库根目录的项目配置文件中,把图片缓存的位置设置为 cacheDir,如下所示:
[caches.images]
dir = ':cacheDir/images'关于文件缓存的更多信息,请参阅配置文件缓存。
第 3 步:提交并推送改动
git add -A
git commit -m "Create amplify.yml"
git push第 4 步:进入 Amplify 控制台
登录 AWS 账号,进入 Amplify 控制台,然后按下 Deploy an app(部署应用)按钮。
第 5 步:选择源码提供商
选择源码提供商(source code provider),然后按下 Next 按钮。
第 6 步:授权访问 GitHub
授权 AWS Amplify 访问你的 GitHub 账号。
第 7 步:选择账号或组织
选择你的个人账号或所属的组织。
第 8 步:授权仓库
授权 Amplify 访问一个或多个仓库。
第 9 步:选择仓库与分支
选择要部署的仓库和分支,然后按下 Next 按钮。
第 10 步:应用设置
在 “App settings” 页面上滚动到底部,然后按下 Next 按钮。Amplify 会读取你在第 1 至 3 步创建的 amplify.yml,而不是使用本页填写的值。
第 11 步:确认并部署
在 “Review” 页面上滚动到底部,然后按下 Save and deploy 按钮。
第 12 步:查看站点
站点部署完成后,按下 Visit deployed URL 按钮查看已发布的站点。
你应当看到什么:第 12 步的页面地址由 Amplify 分配(形如 https://main.xxxxxx.amplifyapp.com)。打开后应当是完整的站点,而不只是一句欢迎语;如果只有平台默认页,说明 artifacts.baseDirectory 或 publishDir 不一致。
失败时:典型报错与排查入口
排查 Deployment 的入口始终是同一个:Amplify 控制台 → 你的应用 → 对应分支 → 构建详情页的日志。日志按 preBuild / build 分节,报错行会标明是哪一个命令失败。
| 症状 | 真因 | 怎么修 |
|---|---|---|
日志里 hugo: command not found |
安装 Hugo 的那一段没有成功(下载失败、版本号不存在),或 Amplify 根本没有执行这份 amplify.yml |
先在日志里搜 Installing Hugo ...:完全没有这一行,说明这段配置没被执行(确认 amplify.yml 在仓库根目录,且当前构建用的是它);有这一行、但随后的 Hugo: 一行是 not installed,说明下载或解压失败,按同一段里 curl/tar 的报错处理 |
| 构建报 Dart Sass 相关错误 | 站点用到 Sass,但 DART_SASS_VERSION 缺失或安装失败 |
检查日志里 Dart Sass: ... 一行;填上版本号,网络超时则重试构建 |
| 构建报模板或参数不存在 | 线上 Hugo 版本与本地不同 | 把 HUGO_VERSION 改成 hugo version 显示的版本并重新推送 |
| 构建成功,但网址 404 或只有默认页 | artifacts.baseDirectory 不是真正的发布目录 |
改成 public(或你配置的 publishDir),重新部署 |
| 页面能打开,样式与图片丢失 | baseURL 仍是本地地址或旧的临时域名 |
把 baseURL 改成最终访问地址后重新推送 |
日志里 Dart Sass: not installed 但构建通过 |
站点其实没用到 Sass | 无需处理:这段输出只是版本记录 |
| 图片每次都重新处理,构建很慢 | 缓存路径与 HUGO_CACHEDIR 不一致 |
核对 cache.paths 与 HUGO_CACHEDIR 指向同一目录 |
更一般的症状分诊(命令找不到 / 没报错但结果不对 / 报错看不懂)见故障排查;上线前想先体检一遍站点,见审计。
域名与重定向
首次部署完成后,Amplify 会为应用分配一个默认域名。它适合用来验证站点是否正常,但不适合作为对外发布的地址。
- 绑定自定义域名后要改
baseURL。 页面里的绝对链接、站点地图和 RSS 都基于baseURL生成。绑定自定义域名后,把项目配置中的baseURL改成该域名并重新提交推送,否则这些地址仍会指向默认域名。 - 404 页面。 Hugo 可以生成
public/404.html。如果希望自定义域名下返回自己的错误页,需要在 Amplify 控制台中配置重定向与重写规则,具体入口以官方文档为准。 - 尾斜杠与重定向。 Hugo 默认输出以
/结尾的 URL。如果平台侧同时配置了强制去除尾斜杠或其它重定向规则,请确认两者不冲突,避免出现多余的跳转链。 - 缓存。 重新部署不等于所有访客立刻拿到新文件,更新样式或图片后要留意旧缓存的影响。
相关资源
要进一步了解如何用 AWS Amplify 托管和管理站点,请查阅官方文档: