Skip to content

docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法 - #3538

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-3533-runner-env-docs
Aug 7, 2026
Merged

docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法#3538
yinlianghui merged 1 commit into
mainfrom
claude/issue-3533-runner-env-docs

Conversation

@yinlianghui

@yinlianghuiyinlianghui commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

Fixes#3533

两处文档教的环境变量用法与实现不符,按 #3527 / #3532 的口径处理。

一、content/docs/utilities/runner.mdx —— 整节删除 "Environment Variables"

前提已复核通过,且核查范围比原单更宽(整个包,不只是 src):

$ grep -rn "import.meta.env|process.env|loadEnv|VITE_" packages/runner --exclude-dir=node_modules --exclude-dir=dist
(无输出)
$ grep -rn "VITE_APP_TITLE" -I . --exclude-dir=node_modules --exclude-dir=.git
content/docs/utilities/runner.mdx:323 ← 全仓仅此一处,即只活在这份文档里
$ grep -rn "VITE_API_URL" packages/ apps/ examples/ scripts/ | grep -v node_modules
(无输出)

@object-ui/runner 一个环境变量都不读,所以「Configure the runner with environment variables」这一整节教的两个变量都不会生效。失败形态与 #3527 相同:读者照做、配了、没有任何报错、也没有任何效果。文档不许描述不存在的能力,因此整节删除,不换变量名续命。

删除后衔接干净:### pnpm test 的代码块之后直接是 ## Package Information,没有孤立的引导语或空行。也没有任何锚点悬空 —— 全仓对 #environment-variables 的引用为零(grep -rn "#environment-variables" -I . 无输出),content/docs/utilities/meta.json 只列页面不列标题,不受影响。

二、content/docs/guide/objectos-integration.mdx:406 —— process.env 改 import.meta.env

该示例注释明写是 frontend/src/config.ts,而 Vite 不向浏览器包注入 process,原样照抄会直接 process is not defined(或恒为 undefined,静默退回硬编码的兜底地址)。

变量名 VITE_API_URL 本身是读者自己应用里的自定义变量(不是 ObjectUI 的契约),是对的 —— 本 PR 只改读取方式,不动变量名。

三、经核定「正确、未改动」的一处

content/docs/guide/building-crud-app.md:306 用 import.meta.env.VITE_API_URL 读读者自定义变量,拼法正确,属正常示例,按分诊裁定未改动。

验证

事前预测 → 实测,全部相符:

检查预测实测
grep -rn "VITE_APP_TITLE" content/00(exit 1)
grep -rn "process\.env\.VITE" content/00(exit 1)
node scripts/check-doc-links.mjsexit 0Docs links are valid. exit 0
node scripts/check-control-bytes.mjsOKOK (scanned 3695 tracked text file(s); skipped 85 binary)
pnpm exec vitest run scripts/ --maxWorkers=2保持绿Test Files 14 passed (14) / Tests 216 passed (216)

关于 vitest 这一项需要说明清楚:scripts/__tests__/ 测的是各个检查脚本自身,没有任何一个文件引用 runner.mdx / objectos-integration / VITE_(grep -rln "runner\.mdx|objectos-integration|VITE_" scripts/ 无输出)。所以这 216 个测试是回归兜底,并没有真正覆盖本 PR 改的内容;真正把本次改动跑过一遍的是 check-doc-links.mjs 与 check-control-bytes.mjs(它们扫真实的 content/ 树)。据实写明,不把它记成「测试验证了本改动」。

另外对两个被改文件做了超出 gate 的控制字符自查(grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]'),无命中。

无 changeset:纯 content 文档改动,依 #3532 先例。

越界发现(已另立单,本 PR 不实现)

#3537 —— runner 真实的 API 基址配置面是 URL 查询参数 api(packages/runner/src/App.tsx:43-57:带 api 参数走 NetworkLoader,缺省走 LocalBundleLoader),而这个真实能力在全仓文档里零处记载。与本单互为镜像:本单是「文档教了实现里没有的东西」,#3537 是「实现里有的东西文档一个字没写」。删掉这节错误的环境变量说明之后,该页关于 API 基址的指引为零 —— 删除仍然是对的,但由此暴露的文档缺口另单处理。

Generated by Claude Code

@claude
docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法
804a8fb
两处文档与实现不符,按 #3527/#3532 的口径处理。
1. `content/docs/utilities/runner.mdx` —— 整节删除 "Environment Variables"。
实测 `@object-ui/runner` 一个环境变量都不读(核查范围为整个包,不只是
`src`):`grep -rn "import.meta.env|process.env|loadEnv|VITE_" packages/runner`
无输出;`VITE_APP_TITLE` 全仓仅存在于这一行文档里。文档不许描述不存在的
能力,因此整节删除而不是换个变量名续命。
2. `content/docs/guide/objectos-integration.mdx` —— `process.env.VITE_API_URL`
改为 `import.meta.env.VITE_API_URL`。该示例注释明写是 `frontend/`,
Vite 不向浏览器包注入 `process`,原样照抄会 `process is not defined`
(或恒为 undefined 静默退回硬编码兜底)。变量名本身是读者自定义的,
不动;只改读取方式。
`content/docs/guide/building-crud-app.md:306` 经核定为正确示例(读者自定义
变量 + 正确的 `import.meta.env` 读法),未改动。
Fixes#3533
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
@vercel

vercelBot commented Aug 7, 2026

Copy link
Copy Markdown

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

1 Skipped Deployment
ProjectDeploymentActionsUpdated (UTC)
objectuiIgnoredIgnoredAug 7, 2026 3:19am

Request Review

This was referenced Aug 7, 2026
Closed
Closed
Closed
Closed
@yinlianghui
yinlianghui marked this pull request as ready for review August 7, 2026 04:05
@yinlianghui
yinlianghui added this pull request to the merge queueAug 7, 2026
Merged via the queue into main with commit 039d2d0Aug 7, 2026
6 checks passed
@yinlianghui
yinlianghui deleted the claude/issue-3533-runner-env-docs branch August 7, 2026 04:06
@yinlianghuiyinlianghui mentioned this pull request Aug 7, 2026
Merged
This was referenced Aug 7, 2026
Closed
Closed
This was referenced Aug 7, 2026
Merged
Merged
Closed
Merged
Closed
Closed
Merged
akarma-synetal pushed a commit to akarma-synetal/objectui that referenced this pull request Aug 10, 2026
@yinlianghui@claude
docs(runner): 删掉 runner.mdx 的幽灵目录与「内置示例 schema」断言,重写 Package Informat…
616353a
…ion (objectstack-ai#3577) (objectstack-ai#3616)
三类结构性虚构,均对 origin/main 逐条复核后处理。范围是整页 8 处锚点,
不是正文列的 3 处 —— 只修 Directory Structure 会让全页继续自相矛盾。
1. 幽灵目录。`packages/runner/src` 下实测只有 App.tsx / LayoutRenderer.tsx /
main.tsx / index.css / lib/ / 测试文件,没有 `schemas/`、没有 `components/`,
包根也没有 `public/`。按 objectstack-ai#3534/objectstack-ai#3539 先例(删手抄目录树,指真源)整块删掉
Directory Structure,换成一段实测过的 prose,并把承重信息落在唯一真实的
元数据目录 `src/app-data/` 上 —— 它由 `.gitignore` 排除、新检出下不存在,
布局与解析顺序由本页自己的 Metadata Loading 一节(objectstack-ai#3581 补)承接。
其余 5 处 `src/schemas/` 引用(Use Cases 两处、Add Custom Schemas、
Best Practices 目录树)一并按 Metadata Loading 的真实契约改写为
`src/app-data/pages/*.json`;页文档形状取 App.tsx 兜底页的
`{ type: 'page', title, body: [] }`,与本页 Metadata Loading 表格里
「the page document (PageNodeSchema)」一致。
2. 「内置示例 schema」。这个包一个 schema 文件都不带:承载它们的
`src/app-data/` 在 `packages/runner/.gitignore:1` 里,缺该目录时
LocalBundleLoader 三个 `import.meta.glob` 编译为 `{}`,`/` 渲染内置兜底
`No index page found.`。What's Included 下那节列七类「Runner 包含的示例
schema」整节改写为读者实际要做的事(往 `src/app-data/` 放 JSON,或用
`?api=` 指后端);下方 `## Example Schemas` 改题为 Schemas to Start From,
并说明这些例子活在文档里、不在包里。
3. Package Information。`Version: 0.3.1` 直接删除,不改成 17.3.0 ——
`@object-ui/runner` 在 `.changeset/config.json` 的 fixed 组里随 39 包同发,
手抄版本号必然再次漂移(分诊亦持此意见);当前版本改为指向 npm 页。
`Type: Application (not published to npm)` 与实测相反:package.json 是
`"private": false` + `publishConfig.access: "public"`,registry 上
`dist-tags.latest = 17.3.0`。改为不随版本漂移的措辞:已发布,但它是应用
不是库 —— package.json 不声明 main/module/exports/types,没有可 import 的
东西(与 PR objectstack-ai#3602 刚给 README 定下的说法一致)。
`src/components/` 保留一处 —— Add Custom Components 的 `// src/components/
MyComponent.tsx`。那是让读者自己建的文件(下方注册片段的相对 import 必须与它
对齐),已在上一句明写「包里不带组件,这个目录你自己加」,不再是「它存在」的
断言。
越界发现另行开单,不在本 PR 修:Features 的「All official plugins included」、
Best Practices 的环境变量小节(objectstack-ai#3538 删了 Environment Variables 整节却漏了它)、
Add Custom Routes 的 react-router-dom(runner 不依赖它,路由是手写
history.pushState)。objectstack-ai#3604 是 README 的另一件事,未触碰。
Fixesobjectstack-ai#3577
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
Co-authored-by: Claude <noreply@anthropic.com>
akarma-synetal pushed a commit to akarma-synetal/objectui that referenced this pull request Aug 10, 2026
@yinlianghui@claude
docs(runner): 删掉 Best Practices 里复活的环境变量配置面 (objectstack-ai#3617) (ob…
d9a03fe
…jectstack-ai#3633)
objectstack-ai#3538(039d2d0,Fixesobjectstack-ai#3533)以「文档不许描述不存在的能力」为由删掉了本页的
`## Environment Variables` 整节,但只删了那一节 —— `## Best Practices` 下的
`### 2. Environment Configuration` 把同一个不存在的配置面又讲了一遍,教读者用
`import.meta.env.VITE_API_URL` / `VITE_ENABLE_ANALYTICS` 配置 Runner。
实现侧不支持这个说法:`grep -rn "import.meta.env|process.env|loadEnv|VITE_"
packages/runner` 整包无输出。同页 `## Metadata Loading`(:95)写着相反的话
——「it reads no environment variables and no config file」,两句相隔约 400 行。
按 objectstack-ai#3538 的口径整节删除,而不是换个变量名续命:Runner 没有任何配置面可以承接
它,唯一的配置入口是 `?api=` 查询参数,已由 Metadata Loading 一节完整覆盖。
Best Practices 余下两条,`### 3. Error Boundaries` 顺延为 `### 2.`。
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
Co-authored-by: Claude <noreply@anthropic.com>
akarma-synetal pushed a commit to akarma-synetal/objectui that referenced this pull request Aug 10, 2026
@yinlianghui@claude
docs(runner): §Add Custom Routes 改写为指向 Add Custom Schemas 的元数据路由说明 (o…
54dd7ec
…bjectstack-ai#3618) (objectstack-ai#3646)
`### Add Custom Routes` 让读者 "Edit src/App.tsx" 并给了一段 react-router 代码。
两处与实现相反:
1. `react-router-dom` 不在 `packages/runner/package.json` 的任何依赖里(dependencies
只有 @object-ui/{components,core,plugin-charts,plugin-kanban,react,types} +
class-variance-authority / clsx / lucide-react / react / react-dom /
tailwind-merge / tailwindcss-animate),全包 grep 'react-router' 零命中 ——
照抄直接 Failed to resolve import。
2. Runner 不是这个路由模型。App.tsx:83 用 useState 持有 currentPath,:120
history.pushState 导航,:127 监听 popstate,:137 把路径喂给
loader.loadPage(currentPath) —— 路由由元数据决定,没有路由表可改。
示例里的 Home / Dashboard / CustomPage 三个组件包里同样不存在。
处置取"保留标题 + 改写为正确说明"而非整节删除:与 objectstack-ai#3538/objectstack-ai#3633 删掉的
`## Environment Variables` / `### 2. Environment Configuration` 不同,那两处描述的
配置面在实现里**不存在**,删掉即无残留问题;而"加路由"是 Runner 真实支持的能力,
只是机制不同(加 JSON 文件),答案就在同页 40 行之下的 `### Add Custom Schemas`。
删掉标题会让按"routes"检索的读者一无所获,并可能重新自行推导出"改 App.tsx"的错误
直觉。本页已有同形态先例:`### Metadata — Supplied by You`(:59)同样是"短说明 +
指向权威小节"的路标节,两处 [Metadata Loading](#metadata-loading) 交叉引用(:63、
:87)也证明页内锚点是本页既有节奏。
`#add-custom-routes` 锚点全仓无任何引用(grep 零命中),故两种处置都不会断链;
保留标题额外保住了站外深链。
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

2 participants

@yinlianghui@claude