Genarrative/.hermes/skills/genarrative-admin-backoffice/references/dev-rust-stack-startup-2026-05-08.md

npm run dev / scripts/dev-rust-stack.sh 启动修复记录

症状

• npm run dev 在 WSL/Linux 下直接失败：
  • It seems like the spacetime version set as current may not exist
  • exec failed for .../.spacetimedb/local/bin/current/spacetimedb-cli
• 失败位置通常在 sync_local_spacetime_install 后、等待 SpacetimeDB 就绪阶段。

根因

• server-rs/.spacetimedb/local 是空 root-dir 时，spacetime start 仍会尝试回调 bin/current/spacetimedb-cli。
• 旧脚本只按 Windows/Git Bash 思路同步 spacetimedb-cli.exe，WSL/Linux 下没有把用户级安装同步到项目 root-dir。
• api-server 首次冷编译时，默认 300 秒超时不够，容易在就绪前被回收。

修复要点

1. 同步本机 SpacetimeDB 安装到项目 root-dir
   • 从 spacetime --version 解析真实 CLI 路径。
   • 将对应版本目录复制到 server-rs/.spacetimedb/local/bin/。
   • 重新建立 bin/current 指向版本目录。
2. 兼容 WSL/Linux 与 Windows
   • 不再只判断 OSTYPE=msys*|cygwin*。
   • 同时检查 spacetimedb-cli 与 spacetimedb-cli.exe。
3. 提高 api-server 就绪等待时间
   • API_SERVER_TIMEOUT_SECONDS 从 300 提升到 600。

复现 / 验证

• 运行 npm run dev。
• 观察日志：
  • SpacetimeDB 能正常启动到 Listening on 127.0.0.1:3101
  • 模块发布成功
  • api-server 进入健康检查等待并最终可访问 /healthz

相关文件

• scripts/dev-rust-stack.sh
• server-rs/.spacetimedb/local/