docs(guide): 改教真正生效的 VITE_SERVER_URL,删除不存在的 MSW 开关

[yinlianghui]

Fixes #3527

只改两个文件:content/docs/guide/deployment.md、content/docs/guide/console.md。

一、前提复核(先证伪,再动手)

在 origin/main = d0d71df 上逐条重测 issue 的三条断言,全部成立:

issue 的断言	我的实测
VITE_API_URL 全仓无源码读取	12 处命中全部落在 content/ 里;packages/ apps/ examples/ scripts/ 零命中
VITE_USE_MOCK_SERVER 没有任何代码分支读它	grep "import.meta.env.VITE_USE_MOCK_SERVER" 零命中;apps/console/src、packages/app-shell/src、examples/console-starter/src 里 msw / setupWorker / mockServiceWorker 全部零命中;全仓无 mockServiceWorker.js 资产
VITE_SERVER_URL 才是真变量	83 处命中。packages/app-shell/src/providers/AdapterProvider.tsx:101 即 `baseUrl: import.meta.env.VITE_SERVER_URL

分诊留的那一问:死开关,还是「丢了读取方」?

triage 评论要求先判定 VITE_USE_MOCK_SERVER 属于哪一类、别默默删掉它的文档。答案是死开关,不是丢失的读取方,证据是 git log -S:

2b7435b76 refactor: remove MSW mock server setup and related configurations   (2026-05-02)
  apps/console/dev/mocks/browser.ts        |  97 ---
  apps/console/dev/mocks/server.ts         |  79 ---
  apps/console/objectstack.config.ts       | 134 ---
  apps/console/src/main.tsx                |  34 +-      ← MSW 初始化从入口摘除
  (另删 13 个 *.msw.test.tsx / dev/__tests__ 文件)

即能力是被有意整体移除的,不是读取方意外丢失。今天全仓 from 'msw' 零命中(msw 只剩 root / plugin-form / plugin-grid 的 devDependency 残留)。因此不另立「读取方丢失」的单,文档里描述该能力的说法直接删除。

二、逐条改写 + 源码锚点

deployment.md

位置	改写	锚点(我实读过的消费点)
环境变量表	删 VITE_USE_MOCK_SERVER 与 VITE_API_URL 两行,换成一行 VITE_SERVER_URL,默认值写 ""(同源)	AdapterProvider.tsx:101;auth apps/console/src/main.tsx:18;i18n apps/console/src/loadLanguage.ts:18;action packages/app-shell/src/hooks/useConsoleActionRuntime.tsx:255/431/515。默认值取自 apps/console/.env.production(VITE_SERVER_URL= 留空,文件里写明「published package 嵌进任意 ObjectStack server,不许烤死 origin」)
新增一句 build-time 说明	Vite 在构建期内联 import.meta.env,只在静态托管的运行期设变量无效	Vite 的 loadEnv 语义;实测见下方「三」
.env.production 示例	改为 VITE_SERVER_URL=https://demo.objectstack.ai,并注明留空即同源	examples/console-starter/.env.production 就是这个值;apps/console/.env.production 是留空那一支
vercel / railway / netlify 三条命令	变量名替换为 VITE_SERVER_URL	同上
Tip	原文「console 默认带 MSW,生产要关掉」整条删除,换成跨源部署的两条真实前置:后端要放行 CORS(Access-Control-Allow-Origin 指向 SPA 源 + Access-Control-Allow-Credentials: true),鉴权 cookie 要 SameSite=None; Secure	apps/console/README.md 的 "Additional backend requirements for cross-origin deployments" 1/2 两条 —— 不是我编的,是把已验证过的那段搬到文档站
Production Build Command	VITE_USE_MOCK_SERVER=false pnpm build → VITE_SERVER_URL=https://demo.objectstack.ai pnpm build	见下方「三」的 turbo 实测
紧随其后的一句	「This is equivalent to the build:server script defined in the console app.」—— build:server 这个脚本今天不存在(apps/console/package.json 的 scripts 里没有;全仓仅在各 CHANGELOG 的历史条目里出现,与 MSW 一起被 2b7435b 移除)。它就贴在我必须改写的构建命令下面,同属一条死指引,一并改成 pnpm build / pnpm build:console 的真实口径	根 package.json: build = turbo run build --filter=!@object-ui/site;build:console = pnpm --filter @object-ui/console build

NODE_ENV 那一行核对后保留:vite build 确实自动置 production,描述属实。

console.md

位置	改写	锚点
93-95(本单点名处)	VITE_API_URL=http://localhost:3000 pnpm console → VITE_SERVER_URL=http://localhost:3000 pnpm dev,并补一句留空即同源	见下方「三」实测
91 的引导句	「To connect to a real ObjectStack server instead of MSW」—— 不改它,93-95 就前后矛盾。改为点名 VITE_SERVER_URL 是决定连哪个后端的开关	同上
14 / 18(Quick Start)	同类顺手改,不隐瞒:pnpm console 与 93-95 里那条是同一条死命令(实测 ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL Command "console" not found),只修其一等于继续教坏的那条;5175 端口错(真值 5180);「with MSW providing a simulated backend」正是分诊要求删除的那条不存在的能力	根 package.json 的 dev = pnpm --filter @object-ui/console dev;apps/console/vite.config.ts:320 port: 5180;apps/console/.env.development:4 VITE_SERVER_URL=http://localhost:3000
122-123(Folder Structure 里的 mocks/ browser.ts # MSW browser worker)	删这两行 —— 该目录已被 2b7435b 删除,是本文件里最后一处 MSW 说法	同上 commit;apps/console/src/mocks 不存在

⛔ 未触碰四个 .env 文件里的死 VITE_USE_MOCK_SERVER(维护者判断,issue 已单列)、未触碰 apps/console/vercel.json、未触碰 content/docs/releases/。无 changeset(纯 content 文档,沿用 #3524 / #3495 的 docs-only 先例)。

三、实测:文档里新写的命令我真跑过

1. 内联 VITE_SERVER_URL 能穿透 pnpm --filter 到 vite,且压过 .env.development

$ VITE_SERVER_URL=http://localhost:9999 pnpm --filter @object-ui/console exec node --input-type=module \
    -e "import {loadEnv} from 'vite'; console.log(loadEnv('development', process.cwd(), 'VITE_').VITE_SERVER_URL)"
http://localhost:9999          ← 内联值胜出

$ pnpm --filter @object-ui/console exec node ...(同上,不带内联 env)
http://localhost:3000          ← .env.development 的基线值

这条必须实测,因为 AGENTS.md 明写经 pnpm --filter … dev 传 env「不可靠」—— 那条是对 DEV_PROXY_TARGET(vite.config 读的 Node 侧变量)的结论;VITE_* 走 Vite 自己的 loadEnv,上面两行是它确实到位的证据。

2. pnpm console 确实不存在

$ pnpm console
 ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL  Command "console" not found
Did you mean "pnpm build:console"?

3. VITE_SERVER_URL=… pnpm build 真的能到达构建 —— 差一点写错的一条

pnpm build 走 turbo,而 turbo.json 的 build 任务只声明了 env: ["NODE_ENV", "VITE_BASE_PATH", "OBJECTSTACK_CLIENT_DIST"],VITE_SERVER_URL 不在其中;turbo 2.10.7 的默认 envMode 是 strict(未声明的变量会被过滤)。按这个推理,新写的构建命令会是又一条无效指引。实跑 dry-run 才看清真相:

$ VITE_SERVER_URL=http://localhost:9999 pnpm exec turbo run build --filter=@object-ui/console --dry=json
taskId:    @object-ui/console#build
envMode:   strict
framework: vite
specified: {"env":["NODE_ENV","OBJECTSTACK_CLIENT_DIST","VITE_BASE_PATH"]}
inferred:  ["VITE_SERVER_URL=623413ff…"]        ← turbo 的 framework inference 认出 vite,自动收 VITE_*

turbo 识别出该包是 vite framework,把 VITE_* 通配自动纳入,strict 模式下仍然透传。文档里那句「Turbo runs in strict env mode, but it detects the console as a Vite package and passes VITE_* through automatically」写的就是这条实测,不是推断。

四、门禁(先写预测,再执行)

预测:全绿且计数不动。 grep -rln 显示 scripts/、packages/、apps/ 下没有任何 *.test.ts* 引用 deployment.md / console.md(ci-cd-pipeline-doc.test.ts 钉的是另一个页面),因此 204 条不应有任何 verdict 移动;diff 纯文本、不新增文件,check-control-bytes 的扫描面数量也应不变。

结果与预测逐条一致:

$ pnpm exec vitest run scripts/ --maxWorkers=2
 Test Files  14 passed (14)
      Tests  204 passed (204)

204 与 PR #3524 在同一 main sha 上记录的基线逐个相同 —— 无 verdict 移动。

$ node scripts/check-doc-links.mjs
Docs links are valid.                       (exit 0)

$ node scripts/check-control-bytes.mjs      (两个文件已 git add 后重跑)
✅  check-control-bytes: OK (scanned 3690 tracked text file(s); skipped 85 binary).

$ grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' content/docs/guide/deployment.md content/docs/guide/console.md
(无命中)

一条门禁绿≠已验证,得说清楚: 我在 console.md:18 新加了页内锚点 [Running with a Real Backend](#running-with-a-real-backend),而 check-doc-links.mjs:158-159 对纯页内锚点是 return true 直接放行的 —— 它的绿不构成该锚点有效的证据。我自己按标题逐字核对:## Running with a Real Backend → slug running-with-a-real-backend,吻合。这就是这条链接正确性的全部证据。

替换后的复查:

$ grep -rn "VITE_API_URL\|VITE_USE_MOCK_SERVER" content/docs/guide/deployment.md content/docs/guide/console.md
(无命中)
$ grep -n -i "msw\|mock" content/docs/guide/deployment.md content/docs/guide/console.md
console.md:18: … There is no bundled mock backend …        ← 唯一残留,且是「不存在」的正确陈述

五、越界发现(只报不改)

1. content/ 里还有 5 处 VITE_API_URL,全在本单文件面之外 —— content/docs/utilities/runner.mdx:322/329/429、content/docs/guide/building-crud-app.md:306、content/docs/guide/objectos-integration.mdx:406。性质与本单两处不同:这些是「读者在自己的应用里自定义一个变量、再用自己的 import.meta.env 读它」的示例代码,不是在教 ObjectUI 自身的环境变量契约,所以不属于「配了没用」那一类。仍建议维护者过一眼(尤其 objectos-integration.mdx:406 用 process.env.VITE_API_URL,在 Vite 应用里是读不到的),但按文件面纪律未动。
2. console.md 的 Folder Structure 代码块整体过期 —— 除我删掉的 mocks/ 外,context/ExpressionProvider.tsx 目录不存在,components/ 下列的 AppHeader.tsx / AppSidebar.tsx / CommandPalette.tsx / ConsoleLayout.tsx / ObjectView.tsx / RecordDetailView.tsx 六项在 apps/console/src/components/ 里一个都没有(实际只有 FormPage / MetadataHmrReloader / PerformanceDashboard / RootLandingRedirect / schema,那六个组件早已迁到 packages/app-shell)。这是结构性漂移,与本单的死环境变量不同类,整块重写需要另行核对,已另立 issue,不在本 PR 顺手改。
3. deployment.md:12 的小瑕疵:「pnpm build (runs turbo run build across all packages)」,实际是 turbo run build --filter=!@object-ui/site(排除文档站)。同一页但非本单类别,未改。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 7, 2026 3:06am