解決 Vercel + Hugo + Git Submodule 部署失敗的問題

Tue, 03 Mar 2026 20:17:00 +0800

問題現象

把 Hugo 部落格推到 GitHub 後，Vercel 的 Git 自動部署一直失敗，Dashboard 上全部顯示紅色的 Error。

但奇怪的是，用 vercel --prod 手動部署卻完全正常。

連續好幾次推送都失敗，只有 CLI 手動部署成功。到底怎麼了？

排查過程

第一步：確認問題範圍

先用 CLI 看看所有部署的狀態：

1

vercel ls

結果一目瞭然：所有 Git 觸發的部署都是 Error，只有手動的是 Ready。

第二步：嘗試從 CLI 查看 build log

1
2


vercel inspect <deployment-url> # 只顯示 status: Error
vercel logs <deployment-url> # 只有 runtime log

CLI 竟然看不到 build 階段的錯誤訊息 😩 這是一個坑——Vercel CLI 的 logs 指令只顯示 runtime log，不顯示 build log。

第三步：從 Dashboard 找到真正的錯誤

進入 Vercel Dashboard → Deployments → 點開失敗的部署，終於看到了：

The 'vercel.json' schema validation failed with the following message: 'build' should NOT have additional property 'command'

原來是 vercel.json 的格式寫錯了！

根本原因

我原本的 vercel.json 長這樣：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "framework": "hugo",
 "build": {
 "command": "hugo --gc --minify",
 "output": "public",
 "environment": {
 "HUGO_VERSION": "0.156.0"
 }
 }
}

這個巢狀的 build 物件是舊版格式，現代 Vercel 的 schema 已經不接受了。

為什麼 CLI 部署卻成功？

因為 vercel --prod 走的是「上傳檔案 → 建置」的流程，它的解析邏輯和 Git 觸發部署用的 schema validation 不完全一樣，所以 CLI 繞過了驗證錯誤。

這也是最容易中招的地方：你會以為設定沒問題（CLI 都成功了啊），但實際上是 CLI 比較寬容。

解決方法

1. 修正 vercel.json

用頂層屬性取代巢狀物件：

1
2
3
4
5
6


{
 "framework": "hugo",
 "buildCommand": "hugo --gc --minify",
 "outputDirectory": "public",
 "installCommand": "git submodule update --init --recursive"
}

重點：

build.command → buildCommand
build.output → outputDirectory
新增 installCommand 處理 Git Submodule

2. 環境變數改用 CLI 設定

1
2


vercel env add HUGO_VERSION production
# 輸入 0.156.0

把 Hugo 版本從 vercel.json 移到 Vercel 的環境變數管理，更乾淨也更安全。

3. 推送驗證

1

git push

這次 Git 觸發的自動部署終於成功了！✅

關於 Git Submodule

如果你的 Hugo 主題是用 Git Submodule 管理的（像大多數 Hugo 教學建議的），Vercel 在 clone 你的 repo 時預設不會初始化 submodule。

所以一定要在 vercel.json 裡加上：

1

"installCommand": "git submodule update --init --recursive"

沒加的話，Hugo 會找不到主題而 build 失敗。

重點整理

踩到的坑	正確做法
`build.command` 巢狀寫法	用頂層 `buildCommand`
`build.output` 巢狀寫法	用頂層 `outputDirectory`
CLI 成功 ≠ 設定正確	要看 Git 觸發的部署結果
CLI `vercel logs` 看不到 build 錯誤	去 Dashboard 看部署詳情
Submodule 沒被 init	加 `installCommand`
環境變數寫在 json 裡	改用 `vercel env` 管理

希望這篇能幫到同樣踩坑的人 🕳️

Vercel on 米雞嘻嘻