1

docs/technical/SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md

@@ -0,0 +1,53 @@
+# SpacetimeDB publish sccache 降级处理
+
+## 背景
+
+Windows 本地执行 `npm run dev:rust` 或 `spacetime publish` 时，`spacetime` 会在内部调用 Cargo 构建 `server-rs/crates/spacetime-module`。因为 `server-rs/.cargo/config.toml` 配置了 `rustc-wrapper = "sccache"`，即使当前 shell 没有设置 `RUSTC_WRAPPER`，Cargo 仍会先执行 `sccache rustc -vV`。
+
+当本机 sccache server 状态损坏、client/server 通信异常或版本残留不一致时，可能出现：
+
+```text
+sccache: error: failed to execute compile
+sccache: caused by: Failed to send data to or receive data from server
+sccache: caused by: Failed to read response header
+sccache: caused by: failed to fill whole buffer
+```
+
+这类错误发生在 rustc wrapper 层，不能说明 SpacetimeDB module 代码本身编译失败。
+
+## 本地开发处理
+
+`scripts/dev-rust-stack.sh` 的 publish 阶段保留首次正常 `sccache` 构建；如果 stderr 命中 sccache 通信或 wrapper 失败特征，则自动在同一 `--root-dir`、同一发布参数下清空本次子进程的 `RUSTC_WRAPPER` 与 `CARGO_BUILD_RUSTC_WRAPPER` 后重试。
+
+该处理只影响本次 publish 子进程，不修改 `server-rs/.cargo/config.toml`，也不删除本地 target 缓存。
+
+## 手动排障命令
+
+优先确认 rustc 本身可用：
+
+```bash
+rustc -vV
+```
+
+如果只想绕过本次 Cargo 构建的 sccache wrapper，可在 Git Bash 中执行：
+
+```bash
+cd server-rs/crates/spacetime-module
+RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build --target=wasm32-unknown-unknown --release
+```
+
+如果需要排查 sccache server 状态：
+
+```bash
+sccache --show-stats
+sccache --stop-server
+sccache --start-server
+```
+
+`sccache --stop-server` 本身也可能因为 server 通道已损坏而失败；此时不应阻断本地开发 publish，先使用 wrapper 降级完成验证。
+
+## 验证
+
+1. `bash -n scripts/dev-rust-stack.sh`
+2. `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo check --target=wasm32-unknown-unknown --release`
+3. 重新运行 `npm run dev:rust`，看到 sccache 通信失败时脚本应打印降级提示并继续真实构建。