Genarrative/docs/technical/SPACETIME_DEV_URI_HOTFIX_2026-04-20.md

Spacetime 开发连接地址热修 2026-04-20

背景

当前前端账号、存档和资料库链路已经切到 SpacetimeDB。

但本地开发默认配置存在一处关键错配：

• 默认数据库名是 maincloud 上的 xushi-p4wfr
• 默认 VITE_SPACETIME_URI 却写成了 ws://127.0.0.1:3000
• 同时 npm run dev 的 Vite 开发服也默认占用 127.0.0.1:3000

结果是页面启动后，浏览器会把账号 WebSocket 误连到 Vite，而不是实际的 SpacetimeDB 服务。

这会直接表现为：

• 页面长时间停留在“正在建立账号连接...”
• 或者账号连接相关逻辑异常，但 npm run dev 终端表面上看起来前后端都已经启动

根因

本次问题不是 server-node 编译失败，而是前端默认环境变量错误：

• src/spacetime/client.ts 内置默认 URI 错误
• .env.example 示例值错误
• scripts/dev-node.mjs 没有把正确的 Spacetime 默认值显式注入启动环境

修复

本次做了三处最小修复：

1. src/spacetime/client.ts

• 默认 VITE_SPACETIME_URI 改为 wss://maincloud.spacetimedb.com
• 默认数据库名继续保持 xushi-p4wfr

2. scripts/dev-node.mjs

• 当本地未配置时，自动注入：
  • VITE_SPACETIME_URI=wss://maincloud.spacetimedb.com
  • VITE_SPACETIME_DATABASE_NAME=xushi-p4wfr
• 启动日志增加当前使用的 Spacetime URI 和数据库名，便于排查

3. .env.example

• 示例值改为 maincloud URI
• 补充说明：若要连本地 spacetime start，需在 .env.local 中显式覆盖为 ws://127.0.0.1:3000

验证

已完成：

• npm run dev
  • Vite 正常启动到 http://127.0.0.1:3000
  • server-node 正常启动到 :8081
  • 启动日志会明确打印当前 VITE_SPACETIME_URI 与 VITE_SPACETIME_DATABASE_NAME
• npm run check:encoding

结论

默认开发链路现在会优先连到和默认数据库名一致的 maincloud Spacetime 服务，不再把账号连接误打到本地 Vite 端口。

如果后续要切回本地 SpacetimeDB，只需要在 .env.local 中显式覆盖 URI，不需要再改代码。