修复报错

docs/technical/SPACETIME_DEV_URI_HOTFIX_2026-04-20.md

@@ -0,0 +1,63 @@
+# 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，不需要再改代码。