Genarrative/docs/technical/SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md

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 通信异常或版本残留不一致时，可能出现：

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 本身可用：

rustc -vV

如果只想绕过本次 Cargo 构建的 sccache wrapper，可在 Git Bash 中执行：

cd server-rs/crates/spacetime-module
RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build --target=wasm32-unknown-unknown --release

如果需要排查 sccache server 状态：

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 通信失败时脚本应打印降级提示并继续真实构建。