docs(runner): §vite.config.ts 改写为指路真实文件 + 点名两个承重不变量 (#3643)

[yinlianghui]

Fixes #3643

content/docs/utilities/runner.mdx 单文件。

前提复核(先复核后动手)

issue 的两条断言都对 origin/main(切点 0d5da5394,含 #3646 的 54dd7ec1f)按内容锚定复核过,全部成立:

断言	复核结果	证据
真实文件无 server 块	成立	packages/runner/vite.config.ts 顶层只有 plugins / resolve / build 三个键
port: 5173 不是配出来的	成立	且 packages/runner/package.json 的 dev 脚本就是裸 vite,没有 --port —— 配置层与脚本层双重确认,5173 纯属 Vite 默认端口
open: true 无中生有	成立	同上,dev 脚本无 --open,runner 不会自动开浏览器
resolve.alias 闭包表被隐去	成立	真实文件 :16-101,含 #3575 的传递闭包不变量与一段可重跑的闭包再推导命令
build.modulePreload: false 被隐去	成立	真实文件 :102-122

取舍:为什么是「说明形态」而不是「换一份更准的代码块」

PM 给的两个选项里取 (a) 改写为说明形态,并且不保留任何配置代码块。理由三条:

1. 围栏代码块本身就是这次的故障源。 一个写着 export default defineConfig({...}) 的块,读者的默认动作是复制粘贴过去。这一节的危险恰恰是「照抄替换真实文件」——那会丢掉别名表,直接复现 packages/runner 按 runner.mdx 的「From Source」步骤起不来:vite 别名表漏了 5 个源码实际 import 的工作区包 #3575。把块换成一份「更准的」节选并不消除这个动作,只是让它下次错得更隐蔽。
2. 别名表是「增长中」的传递闭包,任何节选都是 by construction 的漂移。 表会随着 packages/* 的 import 边增长(packages/runner 按 runner.mdx 的「From Source」步骤起不来:vite 别名表漏了 5 个源码实际 import 的工作区包 #3575 就是它增长时漏了 fields / plugin-detail)。节选首尾 + 省略号,今天准,下一个包进来就不准了 —— 这正是 finding: live-e2e allowlist 的 spec 名单被手抄在两处文档里,每次晋级都会失同步 #3488/docs(guide): 删掉 console.md 已整体过期的 Folder Structure 目录树 #3539 记下的教训,所以不再造一份拷贝。
3. 本页已有先例。 §Where the Code Lives(docs(guide): 删掉 console.md 已整体过期的 Folder Structure 目录树 #3539)就是纯说明形态:指路真实文件、讲清各文件职责、零代码块。同页同体例,读者不会觉得割裂。

附带买到的一个机械保险:指向真实文件用的是 https://github.com/objectstack-ai/objectui/blob/main/packages/runner/vite.config.ts 这个形状 —— scripts/check-doc-links.mjs 会把它当仓内引用校验路径是否存在(#3536 那条规则),所以文件哪天被挪走或改名,这条链接会机械变红,而不是静默烂掉。裸 backtick 路径没有这个保险。

前后对照

修前(:161-176)—— 一个真实文件里不存在的配置:

The Runner uses Vite for development and building:

  export default defineConfig({
    plugins: [react()],
    server: {
      port: 5173,      ← 真实文件无 server 块
      open: true,      ← 无中生有
    },
  })

承重的 resolve.alias 与 build.modulePreload 一个字没提。

修后 —— 说明形态,四段:

1. 指路真实文件(受校验的 blob/main 链接),并写明「刻意不在本页复制」及其原因;
2. 明确写出否定事实:真实文件没有 server 块,5173 是 Vite 默认端口,pnpm dev 不会开浏览器 —— 这条同时给同页 §Port Already in Use(教你自己加 server.port)接上了正确前提;
3. 点名两个不许删的面及其原因:
   • resolve.alias —— 它就是 runner 能免 pnpm -w build 直接从源码启动的机制,必须是传递闭包;漏一个 specifier 会退回 Node 解析、落到不存在的 packages/*/dist,dev server 对整条 import 链返回 HTTP 500(packages/runner 按 runner.mdx 的「From Source」步骤起不来:vite 别名表漏了 5 个源码实际 import 的工作区包 #3575:plugin-kanban 被别名了,它 import 的 fields / plugin-detail 没有);
   • build.modulePreload: false —— 别名表不按 serve 收窄,pnpm build 同样从源码打包,图标微 chunk 不再内联(packages/runner 按 runner.mdx 的「From Source」步骤起不来:vite 别名表漏了 5 个源码实际 import 的工作区包 #3575 实测 10 → 1776 个 asset),Vite 默认 modulePreload: true 会给每个发 preload(index.html 实测 546 B → 145 KB),懒加载反成劣化;
4. 末尾一条 ⛔:不要把任何指南里的 vite 配置贴到该文件上。

数字全部取自真实文件注释里 #3575 的实测值,并在正文里写明「实测于补全别名表时」——按测量时点表述,不会随包数增长而变假。

验证(先预测后跑)

预测	结果
修前 grep open: true / port: 5173 有命中	✅ 修前 2 处(:172 port: 5173、:173 open: true)
修后同一 grep 0 命中	✅ hits=0
修后该节提及两个承重面	✅ resolve.alias :176、build.modulePreload :187、modulePreload: true :192
check-doc-links 修前修后均绿	✅ 两次均 Links are valid across 7 scan roots.(exit 0);新增的 blob/main 链接被该 gate 实际校验通过
check-control-bytes 绿 + 自扫干净	✅ OK (scanned 3661 tracked text file(s));另跑 grep -naP 扫 \x00-\x08\x0b\x0c\x0e-\x1f 无命中,file 报 UTF-8 text

MDX 可解析性:新增文本里唯一的尖括号是一个代码跨度内的路径占位符(尖括号包住 pkg,位于 packages/ 与 /dist 之间)。同一文件已在线上使用完全相同的形状 —— :65、:104、:113-115 以及 :106 的小节标题里,都有尖括号包 base 的 ?api= 占位符与 GET 请求行。形状已被生产渲染验证,无需另跑 MDX 解析。

注:上一版 PR 正文在这一段里直接写了那两个占位符的字面形式,被 GitHub 正文 sanitizer 当成 HTML 标签整段吃掉(存下来变成 packages//dist、?api=),正好把这段唯一的论据抹平。已回读确认并改成描述形式。被吃的只是 PR 正文,.mdx 文件里的字面尖括号完好 —— 见本 PR diff。

无 changeset:站点文档改动,不进 39 包固定组的发布物,依 #3633/#3646 先例。

文件面纪律

单文件 content/docs/utilities/runner.mdx,逐路径 git add,未用 git add -A。未碰 packages/runner/vite.config.ts 本体(issue 里也明确写了「不建议反向操作」——往真实文件里加 server 块是产品决定,不归 docs 卡),未碰 #3619 的 Features bullet。

越界发现(只报不改)

通读该节邻接后新发现一处同类断言,已另开 #3652,不在本 PR 修:

• content/docs/utilities/runner.mdx 两处叫读者去 src/main.tsx 找/加插件 import,但真实 main.tsx 零插件 import(在 App.tsx),且与同页 §Where the Code Lives 自相矛盾 #3652 —— §Adding Custom Plugins 第 2 步与 §Troubleshooting → Plugin Not Loading 都叫读者去 src/main.tsx 找/加插件 import,但真实 main.tsx 只有 18 行纯 React 挂载、零插件 import;两个预装插件的 side-effect import 在 App.tsx :13-15。这与同页 §Where the Code Lives 自己写的「App.tsx … imports the pre-installed plugins」直接打架,且让「插件没加载」的排查步骤指向一个永远看不到 import 的文件。去重已做:content/docs/utilities/runner.mdx §Best Practices 的 Error Boundaries 从 @object-ui/components 导入 ErrorBoundary,但该符号在 app-shell,且 runner 不依赖 app-shell #3635 / content/docs/utilities/runner.mdx Features 写「All official plugins included」,实际只预装 kanban + charts 两个,与同页下方清单打架 #3619 / packages/runner/README.md 的插件清单两处写成开放集合(§Features 的「etc.」、§Pre-installed Plugins 的非插件条目),实际只预装 kanban + charts 两个 #3632 / packages/runner/vite.config.ts 的 @object-ui/data-objectql 别名指向不存在的包目录（全仓唯一引用） #3593 均不覆盖。

---

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 5:15pm