docs: improve deployment troubleshooting (#1011)

* docs: improve deployment troubleshooting docs

* docs: fix GitHub casing in FAQ

* docs: clarify subdomain address creation

vitepress-docs/docs/zh/guide/ui/pages.md

@@ -115,9 +115,12 @@ const generate = async () => {
     - 此处 worker 域名为后端 api 的域名，比如我部署在 `https://temp-email-api.awsl.uk`，则填写 `https://temp-email-api.awsl.uk`
     - 如果你的域名是 `https://temp-email-api.xxx.workers.dev`，则填写 `https://temp-email-api.xxx.workers.dev`
     - 不要填写前端 `Pages` 自己的域名，也不要带 `/admin`、`/api` 等路径，否则前端请求会打到错误地址，可能出现 `Cannot read properties of undefined (reading 'map')` 或 `405 Method Not Allowed`
+    - 填写前请先在浏览器打开 `https://你的worker域名/open_api/settings`，确认返回 JSON；如果返回 HTML、404、405 或 Cloudflare 挑战页，请先修复 Worker 绑定、变量或安全策略
 
     > [!warning] 注意
     > `worker.dev` 域名在中国无法访问，请自定义域名
+    >
+    > 不要给后端 API 域名开启 Under Attack、Bot Fight、Managed Challenge 等会返回浏览器挑战页的安全策略。前端 XHR 请求无法完成这些挑战，常见表现是 `Network Error`。
 
     <div :class="$style.container">
         <input :class="$style.input" type="text" v-model="domain" placeholder="请输入以 https:// 开头的后端 API 地址"></input>
@@ -133,6 +136,8 @@ const generate = async () => {
     > 修改压缩包里面的 index-xxx.js 文件 ，xx 是随机的字符串
     >
     > 搜索 `https://temp-email-api.xxx.xxx` ，替换成你 worker 的后端 API 根地址，然后部署新的 zip 文件。如果填成前端 Pages 域名，常见现象就是页面报 `map` 错误或接口返回 `405`
+    >
+    > 如果第一次填错后重新部署仍然报错，请用无痕窗口测试或清理浏览器缓存，避免浏览器继续使用旧的前端资源。
 
 4. 选择 `Pages`，点击 `Create Pages`, 修改名称，上传下载的 zip 包
 

vitepress-docs/docs/zh/guide/ui/worker.md

@@ -16,6 +16,9 @@
 
     ![worker-runtime](/ui_install/worker-runtime.png)
 
+    > [!IMPORTANT]
+    > `nodejs_compat` 必须添加成功后再部署 `worker.js`。如果缺少该兼容标记，常见错误是 `No such module "path"`、`No such module "node:stream"`，前端也可能只显示 `Network Error`。
+
 4. 下载 [worker.js](https://github.com/dreamhunter2333/cloudflare_temp_email/releases/latest/download/worker.js)
 
 5. 回到 `Overview`，找到刚刚创建的 worker，点击 `Edit Code`, 删除原来的文件，上传 `worker.js`, 点击 `Deploy`
@@ -23,7 +26,7 @@
     > [!NOTE]
     > 上传需要先点击左侧菜单的 Explorer,
     > 在文件列表的窗口里点击鼠标右键，在右键菜单里找到 `Upload`,
-    > 请参考下面的截图
+    > 请参考下面的截图。不要在编辑器中手动创建 `\worker.js` 这类带反斜杠的路径；如果保存时报 `No file system handle registered (\worker.js)`，请回到 Explorer 文件列表右键上传根目录的 `worker.js`，然后再点击 `Deploy`。
     >
     > 参考: [issues156](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/156#issuecomment-2079453822)
 
@@ -56,7 +59,7 @@
 7. 点击 `Settings` -> `Bindings`, 点击 `Add Binding`, 名称如图，选择刚刚创建的 D1 数据库，点击 `Add Binding`
 
     > [!NOTE] 重要
-    > 注意此处 `D1 Database` 的绑定名称必须为 `DB`
+    > 注意此处 `D1 Database` 的绑定名称必须为 `DB`，必须是大写。绑定名写成 `db`、`DATABASE` 或其他值时，`/open_api/settings`、`/admin/*` 等接口会异常，前端常见表现是页面初始化报 `map` 错误或 `Network Error`。
 
     ![worker-bindings](/ui_install/worker-bindings.png)
 
@@ -64,12 +67,14 @@
 
     ![worker-d1-2](/ui_install/worker-d1-2.png)
 
-8. 点击 `Settings` -> `Trggers`, 这里可以添加自己的域名，你也可以使用自动生成的 `*.workers.dev` 的域名。记录下这个域名，后面部署前端会用到。
+8. 点击 `Settings` -> `Triggers`, 这里可以添加自己的域名，你也可以使用自动生成的 `*.workers.dev` 的域名。记录下这个域名，后面部署前端会用到。
 
     > [!NOTE]
     > 打开 `worker` 的 `url`，如果显示 `OK` 说明部署成功
     >
     > 打开 `/health_check`，如果显示 `OK` 说明部署成功
+    >
+    > 打开 `/open_api/settings`，如果返回 JSON，说明前端初始化依赖的公开配置接口可用。部署 Pages 前建议先确认这个地址正常。
 
     ![worker3](/ui_install/worker-3.png)
 
@@ -105,3 +110,5 @@
 
     > [!NOTE]
     > 选择 `cron` 表达式，输入 `0 0 * * *`（此表达式表示每天午夜运行），点击 `Add` 增加。请根据您的需求调整此表达式。
+    >
+    > 只在 admin 页面开启自动清理配置还不够，必须添加 Cron Trigger 后 Worker 的 `scheduled` 事件才会运行。D1 到达容量上限后会出现 `D1_ERROR: Exceeded maximum DB size`，新邮件无法继续写入，表现为“突然收不到邮件；删除几封后恢复”。