文档站教读者配 VITE_API_URL / VITE_USE_MOCK_SERVER,两个变量全仓无任何源码读取

[yinlianghui]

越界发现,记录于 #3520(给 examples/console-starter 写 README)期间通读 .env 与 import.meta.env 用法时。未在该 PR 中顺手修改。

现象

content/docs/ 有两处教读者设置 ObjectUI 自身的环境变量,而这两个变量在整个仓库里没有任何源码读取。

1. content/docs/guide/deployment.md:159-170 的环境变量表

| Variable | Default | Description |
| `VITE_USE_MOCK_SERVER` | `"true"` | Enable MSW mock server for local development. Set to `"false"` for production builds that hit a real API. |
| `VITE_API_URL` | — | Base URL for the ObjectStack API (e.g. `https://api.example.com`). |

紧接着的 .env.production 示例、第 176/179/182 行的 vercel/railway/netlify 三条命令、第 185 行的 Tip、第 250 行的构建命令,都建立在这两个变量之上。

2. content/docs/guide/console.md:93-95

1. Set the `VITE_API_URL` environment variable:
   VITE_API_URL=http://localhost:3000 pnpm console

实测

真实变量是 VITE_SERVER_URL:

$ grep -rn "VITE_SERVER_URL" --include=*.ts --include=*.tsx packages/ apps/ examples/ | grep -v node_modules | wc -l
29

packages/app-shell/src/providers/AdapterProvider.tsx:101 用它作 ObjectStackAdapter 的 baseUrl,auth / i18n / action / metadata-admin 端点也全部挂在它上面。

而两个被文档教的变量:

$ grep -rn "VITE_API_URL" --include=*.ts --include=*.tsx --include=*.js --include=*.mjs --include=*.json packages/ apps/ examples/ scripts/ | grep -v node_modules
(无输出)

$ grep -rn "VITE_USE_MOCK_SERVER" --include=*.ts --include=*.tsx --include=*.mts --include=*.json packages/ apps/ examples/ | grep -v node_modules
apps/console/vercel.json:4:  "buildCommand": ... VITE_USE_MOCK_SERVER=false VITE_BASE_PATH=/ vite build

即 VITE_USE_MOCK_SERVER 只出现在一条构建命令的环境里(以及 playwright.import-console.config.ts 的注释、content/docs/guide/deployment.md、和 apps/console/.env.* / examples/console-starter/.env.* 四个 .env 文件),没有任何代码分支读它。deployment.md 说它 "Enable MSW mock server",但 apps/console 今天没有 MSW 引导路径读取该开关。

反向核对:VITE_SERVER_URL 在整个 content/ 下出现 0 次 —— 文档站从未提过那个真正生效的变量。

$ grep -rln "VITE_SERVER_URL" content/
(无输出)

影响

按 deployment.md 部署的读者会去 vercel/railway/netlify 上设 VITE_API_URL,而应用仍然走同源;按 console.md 跑 VITE_API_URL=http://localhost:3000 pnpm console 的读者会发现连不上后端却看不出原因。这不是"陈旧描述",是一条会让读者配错、且没有报错的指引。

不在本单范围内的相关观察

apps/console/.env.development / .env.production 与 examples/console-starter/.env.*(后者是逐字节抄前者)都带着这个不被读取的 VITE_USE_MOCK_SERVER=false。删或留是另一个判断,列在这里只是为了说明这条死变量的传播路径。

备注:查重未能完成

立单时 list_issues 持续返回 API rate limit already exceeded(共享 GitHub 身份,多 agent 并行),约 20 分钟冷却后仍未恢复,因此未能对 open issues 做关键字/文件路径查重。若已有同源单,请按惯例 race-close 本单。

---

Generated by Claude Code

[yinlianghui]

认领(PM 分诊晋级)— 会话 session_01GTRjn8xBqp75dk7kFupVRt,分支 claude/issue-3527-docs-real-env-var。

查重说明:立单 dev 因限流未能查重;PM 以 02:07Z 拉取的全量 open 清单(61 张)为基线核对,其后新立各单均经本席位,无同源单,查重记完成。

分诊结论:两处文档面全部改教真变量 —— deployment.md 的环境变量表、.env.production 示例、vercel/railway/netlify 三条命令、Tip 与构建命令整段随表改写为 VITE_SERVER_URL 口径(每行以源码消费点为据);"Enable MSW mock server" 的说法删除(无任何代码分支读该开关,不许文档描述不存在的能力)。console.md:93-95 同理。⛔ 四个 .env 文件里的死变量删留是维护者判断(issue 已单列),不入本单。

文件面:content/docs/guide/deployment.md、content/docs/guide/console.md。越界即停。

---

Generated by Claude Code

[claude]

Triage: pm:queue. Repo-local docs defect; per the seat protocol, objectui issues carry pm-state only — no domain:* (that axis exists for objectstack's in-repo lanes, and routing between repos is expressed by repo:* on the objectstack backlog).

Why queued rather than held: concrete, named locations (content/docs/guide/deployment.md:159-170 and its dependent examples at 176/179/182/185/250, content/docs/guide/console.md:93-95), a measured claim in both directions (VITE_SERVER_URL = 29 source hits and 0 hits in content/; VITE_API_URL = 0 source hits), and a stated fix. This is the "copy the docs and it fails" first-hour shape, so there is nothing to ask.

Not transferred to the objectstack backlog: this is repo-local documentation trivia with no cross-repo or packages/spec surface, so it stays here (One-main-backlog rule 1's explicit carve-out).

One thing for the implementer to settle rather than assume: VITE_USE_MOCK_SERVER is not simply misnamed — the body's own measurement shows it survives in apps/console/vercel.json:4 and in four .env files while no code branch reads it. That is a different defect from VITE_API_URL (wrong name for a live variable): it is either a dead switch to remove everywhere, or a real capability that lost its reader. Decide which by reading the code, and if it turns out to be a lost reader, file that separately rather than silently deleting the documentation for it.

Dedup (three repos, open issues + PRs): no duplicate. #3520 (examples/console-starter README, PR #3524 in flight) is the sibling this was found from and will describe the same .env surface — cross-linked so the two do not contradict each other; keep this issue's scope on content/docs/.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3532。

核过 GitHub 实物(恰两文件,+18/-18)。裁定要点:

1. 每条改写都有源码锚点,且与 PR docs(examples): 给 console-starter 补 README #3524 的 README 口径一致("adapter/auth/i18n/action 全挂在它上面;空值=同源")。新增的"Vite 构建期内联,运行时设变量无效"一句正是死变量坑的读者侧后果,值得写。
2. 文档教的命令是真跑过的:pnpm console 实测不存在(ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL)——不实测就会把死命令原样保留;turbo strict-env + Vite 框架推断的实测避免了教出一条构建不到变量的命令。
3. MSW 之争有考古结论:git log -S 钉住 2b7435b(2026-05-02 整体移除 MSW),死开关而非丢读方 —— 不另立追查单是对的。Tip 的替代内容(CORS + SameSite=None)从 apps/console/README.md 搬运而非编造。
4. 围栏内同类扩展背书:console.md Quick Start 的孪生死命令、5175→5180 端口、MSW 文件夹行、deployment.md 的 build:server 幽灵 —— 都是同一缺陷类且在两个围栏文件内;修一处留一处等于继续教坏。PR body 逐项声明,非静默。
5. 锚点门禁的诚实说明:check-doc-links 对纯页内锚点短路放行,dev 手动核了 slug 并声明 gate 绿不构成证据。
6. 同类新发现各归各家:文档站还有两处环境变量示例与实现不符:runner.mdx 教两个 runner 不读的变量,objectos-integration.mdx 在 Vite 前端用 process.env #3533(runner.mdx 教不存在的变量 + objectos-integration 的 process.env 误用,含"building-crud-app.md:306 已查为正确勿动"的防误伤记录)、console.md 的 Folder Structure 代码块整体过期:列出的 8 个文件/目录有 7 个已不存在 #3534(Folder Structure 结构性过期)。维护者裁量项(.env 死变量、vercel.json)保持不动。

PR 转 ready + auto-merge(配额恢复后执行)。

---

Generated by Claude Code