Astro 与 Hugo：静态站框架在 Pages 上的部署参数

读完这篇你能做到：把 Astro 或 Hugo 项目接到 Pages 上，一次填对构建命令和输出目录，锁定框架版本避免某天构建突然失败，并且知道什么时候该切到 SSR 模式、什么时候保持纯静态更省事。

框架选型不是这篇的重点，两个都能在免费档跑得很好。真正决定成败的是三个参数：构建命令、输出目录、版本号。填错任何一个，构建日志看起来都像"成功"，但站点是 404。

前置是项目已经在本地构建通过，Pages 侧的账号与项目准备见 67-pages-getting-started.md。

1. Astro

纯静态 Astro 项目（output 默认是 static）只需要两个参数：

npm run build 内部就是 astro build，产物落在 dist，包含 HTML、CSS、JS 和经过处理的图片资源。这类站点在 Pages 上完全不需要 Functions，静态请求不计费。

需要环境变量时，Astro 只把 PUBLIC_ 前缀的变量暴露给客户端。服务端才用的值不要加这个前缀，否则会被打进产物。

用 SSR 时情况变了：要装 @astrojs/cloudflare 适配器，output 改成 server，构建产物里会多出 _worker.js。Pages 检测到 _worker.js 就把它当 Functions 入口，此时所有请求都会进 Function，计费方式跟着变。纯内容站没有登录、没有个性化渲染，保持 static 更划算。

2. Hugo

Hugo 的参数同样只有两个，但版本要显式锁：

HUGO_VERSION 是 Hugo 项目在 Pages 上最容易漏的一项。不写就用镜像里的默认版本，某个新语法（比如更新的模板函数）在旧版本上直接报错，而本地因为装的是新版一切正常。

主题用 git submodule 引入时，克隆下来的仓库里 themes/ 是空的。构建命令前面要补一步：

git submodule update --init --recursive && hugo --gc --minify

用 Hugo Modules 的方案要求构建环境里有 Go，Pages 的构建镜像不保证提供，所以团队协作的项目用 submodule 更稳。

--gc 清理无用缓存，--minify 压掉多余空白。两个参数对构建时间影响很小，对产物体积有实际帮助。

baseURL 要写成最终域名。写成相对路径时，RSS、sitemap 和绝对链接里会出现错误的地址，本地预览看不出问题，上线后才发现订阅源里的链接全是坏的。

主题以 submodule 引入时，更新主题后要把 submodule 指针一起提交。只在自己机器上 git pull，云端构建会停在旧版本上，表现为"本地改了，线上没变"。

3. 两个框架的共同坑

输出目录写错。Astro 是 dist，Hugo 是 public，混用会得到一次"成功"的构建和一个 404 的站点。判断方法：部署详情里看上传的文件数，个位数就是目录填错了。

大小写不一致。Linux 构建环境区分大小写，Hugo 的模板文件名、Astro 组件导入路径都要对得上。本地不报错不代表云端能过。

构建命令里重复装依赖。写了 npm install && npm run build 会让安装跑两遍，多花一分钟，偶尔还会因为 lock 文件状态不一致出问题。

图片直接堆在仓库里。两个框架都支持构建期图片处理，但原图仍会进 Git 历史。图片量大的站点把原图放对象存储，构建时只引用 URL，做法见 73-image-optimization.md。

4. 部署步骤

1. 把项目推到 GitHub 或 GitLab，确认 npm run build 或 hugo 在干净环境下能跑通。
2. 控制台 Workers & Pages → Create application → Pages → Connect to Git，选中仓库。
3. 框架预设里选 Astro 或 Hugo，预设会填好命令和输出目录；没有预设就手动填上表里的值。
4. 加环境变量。Astro 加 NODE_VERSION，Hugo 加 HUGO_VERSION。
5. Save and Deploy，看构建日志。
6. 打开 *.pages.dev 确认首页、文章页、静态资源都能加载。

第 6 步别只看首页。Hugo 的 taxonomy 页和 Astro 的动态路由最容易在部署后出现 404，因为本地预览服务器会做路径回退，静态托管不会。

常见问题

Hugo 构建报找不到主题。

themes/ 目录是空的，submodule 没初始化。按上一节把 git submodule update --init --recursive 加进构建命令，或者在本地 init 之后把主题目录一起提交。

Astro 项目用了 base 配置，部署后样式全丢。

base 是给部署在子路径用的（比如 GitHub Pages 的 /repo/）。Pages 部署在域名根路径，base 要留空或设成 /，否则资源 URL 会多一层前缀。

两个框架都能在 Pages 上跑，选哪个。

内容为主、模板逻辑简单，Hugo 构建快、依赖少；需要组件化、想在同一套代码里写交互，Astro 更顺。两个都能接 Markdown，也都能在 Pages 免费档跑满。选型纠结的时候，用 52-workers-vs-pages.md 里的三个问题先确认该不该用 Pages。

小结

Astro 和 Hugo 在 Pages 上的部署差异，集中在一张两行的参数表上。填对命令与输出目录，锁住版本号，构建就稳了。

剩下的判断是输出模式。纯静态产物不产生 Function 调用，免费额度只受文件数和单文件大小约束；一旦引入 SSR 适配器，请求开始计入 Workers 额度，收益和成本要一起算。构建侧的通用配置（监视路径、分支命令、依赖缓存）在 70-pages-build-cache.md。

数据来源与检索时间

检索时间 2026-11-10。

核验说明

• 文档部分：Pages 侧的文件数与大小上限来自 2026-11-10 抓取的官方页面；框架输出目录的对应关系参考官方 Routing 页列出的框架表。
• 未执行：本机没有 Pages 权限，没有部署过 Astro 或 Hugo 项目。两个框架的构建命令是按其默认脚本写的，未在 Pages 构建镜像里跑过。
• 未执行：HUGO_VERSION 的具体值只给了写法，没有指定某一个版本号，因为镜像默认版本未核实。
• 未验证：Hugo Modules 需要 Go 环境这一点，依据构建镜像的常见限制推断，未查证官方说明，正文已标注为"不保证"。
• 本地构建验证：无。