From c1ebef77c6cf581cc0d65fbb253c561feefaa251 Mon Sep 17 00:00:00 2001
From: RoboZephyr <276202023+RoboZephyr@users.noreply.github.com>
Date: Fri, 15 May 2026 17:58:26 +0800
Subject: [PATCH] =?UTF-8?q?docs(cloudflare):=20=E6=96=B0=E5=A2=9E=E5=9D=91?=
 =?UTF-8?q?=203=20-=20wrangler=20pages=20deploy=20=E5=A4=9A=E8=A1=8C=20com?=
 =?UTF-8?q?mit=20=E8=A2=AB=20CF=20=E6=8B=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CF Pages deployment API（错误码 8000111）不接受带换行的 commit message。
wrangler 默认会把 git log -1 的 subject+body 整块发过去，于是带 body 的提交
就会 deploy 失败。错误信息称"not valid UTF-8"是误导——实际拒的是换行符。

加了坑 3 完整说明 + 两种修法（手动 --commit-message "$(git log -1 --pretty=%s)"
或在项目里写 scripts/deploy.sh 封装）。错误调试速查表也补了 8000111 + 8000007。

发现来源：classics-learning 项目 deploy 时踩到，单行中文 commit 没事，
本次 commit 带了 body 才暴露。
---
 library/cloudflare/module.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/library/cloudflare/module.md b/library/cloudflare/module.md
index 979e3e6..5b25993 100644
--- a/library/cloudflare/module.md
+++ b/library/cloudflare/module.md
@@ -94,6 +94,36 @@ curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/pages
   -d '{"name":"my-subdomain.example.com"}'
 ```
 
+**坑 3：`wrangler pages deploy` 默认把多行 commit message 喂给 CF，CF 拒**。CF Pages deployment API 不接受带换行的 commit message，wrangler 默认会跑 `git log -1` 把 subject + body 整块发过去。**只要本次 commit 写了 body**（git 标准格式 = subject + 空行 + body），deploy 末段就会报：
+
+```
+✘ A request to the Cloudflare API failed.
+  Invalid commit message, it must be a valid UTF-8 string. [code: 8000111]
+```
+
+**错误信息有误导性**——内容本身是合法 UTF-8（中文/emoji 都行），CF 真正拒的是**换行符**。
+
+**修法**（任选）：
+
+```bash
+# 方法 A：每次手动只取 subject 行
+npx wrangler pages deploy . --project-name my-site \
+  --commit-message "$(git log -1 --pretty=%s)" --commit-dirty=false
+
+# 方法 B：在项目里写个 scripts/deploy.sh，把这事儿封装一次（推荐）
+cat > scripts/deploy.sh <<'EOF'
+#!/bin/sh
+set -e
+cd "$(dirname "$0")/.."
+SUBJECT=$(git log -1 --pretty=%s)
+npx wrangler pages deploy . --project-name my-site \
+  --commit-message "$SUBJECT" --commit-dirty=false
+EOF
+chmod +x scripts/deploy.sh
+```
+
+**注意 wrangler 4.x 还没修这个**——这是 wrangler 应该做的 sanitize（截掉换行 / 只取 subject），它没做。文件已经会上传到 blob storage，只是 deployment 记录没建出来，所以**重试不会重复上传**，只会再次失败在最后一步。
+
 **常见坑**：
 - 第一次 deploy 会自动建 project，但默认绑定 `main` 分支——如果你本地不在 main，加 `--branch <name>` 显式指定
 - Pages 单文件 ≤ 25 MB，单 deploy 总文件数 ≤ 20000；超了静默失败，没有提前校验
@@ -411,5 +441,7 @@ npx wrangler kv namespace create MY_KV
 | 7000 | No route for requested host | 路径里 zone_id 错了 |
 | 81044 | Record name conflict | DNS 同名同类型记录已存在 |
 | 7003 | Could not route to /xxx | API 路径打错（少 /accounts 段最常见）|
+| 8000007 | Project not found | Pages 项目还没建，先 POST `/accounts/{aid}/pages/projects` |
+| 8000111 | "Invalid commit message, it must be a valid UTF-8 string" | **不是 UTF-8 问题**，是 commit message 带了换行（subject + body）。Pages deploy 时只取 subject 喂给 `--commit-message`，详见 Pages 部署「坑 3」 |
 
 **Debug 第一步永远是**：把 response body 完整 print，CF 错误信息很详细。