Troubleshooting Deploy Hugo Site with Vercel

Jun 24, 2025

Issue 1 - 部署完成后，主页是 RSS 的 XML 页面

按照 Vercel 的官方文档部署之后，主页是 RSS 的 XML 页面。原因是 Vercel 自带的 Hugo 版本太低，解决方法如下：

在本地根目录下添加 vercel.json文件，在其中将定义 Hugo 版本、Go 版本以及构建命令（buildCommand）。在 Vercel 中将 Hugo 设置为框架预设（Framework Preset）后，这些配置将会被自动检测。

{
  "build": {
    "env": {
      "HUGO_VERSION": "0.147.8",
      "GO_VERSION": "1.24.4"
    }
  },
  "buildCommand": "hugo --gc --minify && npx pagefind --site public",
  "outputDirectory": "public"
}

Hugo 版本和 Go 版本可以通过 hugo env 命令查看。

Issue 2 - 部署完成后，点击 Vercel 自动生成的 URL，网站样式显示不正常

通过查看浏览器的 Developer Tools，发现请求的 CSS 地址都是 hugo.toml 中设置的 Domain；所以只要在 Vercel 中把 Domain 设置好，直接访问 Domain 网站就会正常显示。

Issue 3 - ReferenceError: PagefindUI is not defined

现象描述：个人博客用 PagefindUI 添加搜索功能后，本地的 localhost 都可以正常使用搜索功能，但是部署之后的网站无法使用。
排查原因：在我的库里没有发现 public 文件夹，因为还没有执行 hugo 命令来构建静态网页，也就不会生成 Pagefind 所依赖的输出内容。Pagefind 是后处理工具，必须在你执行 hugo 命令之后才能运行。
解决方案：
1. 执行 hugo --gc --minify 构建生成静态网页
2. 运行 Pagefind，扫描 public 生成索引 npx pagefind --site public
3. 部署整个 public 到 Vercel