Skip to content

fix(docs): 修复 docs:dev 全新 checkout 无法启动#130

Merged
cc-hearts merged 1 commit into
mainfrom
fix/docs-dev-build-token
Jul 10, 2026
Merged

fix(docs): 修复 docs:dev 全新 checkout 无法启动#130
cc-hearts merged 1 commit into
mainfrom
fix/docs-dev-build-token

Conversation

@cc-hearts

Copy link
Copy Markdown
Member

🤔 本次变更属于 ...

  • 🆕 新功能
  • 🐞 Bug 修复
  • 📝 站点 / 文档改进
  • 📽️ Demo 改进
  • 💄 组件样式改进
  • 🤖 TypeScript 类型定义改进
  • 📦 包体积优化
  • ⚡️ 性能优化
  • ⭐️ 功能增强
  • 🌐 国际化
  • 🛠 重构
  • 🎨 代码风格优化
  • ✅ 测试用例
  • 🔀 分支合并
  • ⏩ 工作流
  • ⌨️ 无障碍改进
  • ❓ 其他(请说明)

🔗 相关 Issue

无对应 Issue。复现:在全新 checkout 上执行 vp run docs:dev(或 pnpm docs:dev)会因缺失 token 资源而崩溃(测试 #129 时发现,但该问题在 main 上早已存在,与搜索功能无关)。

💡 背景与方案

问题: token-meta.jsontoken.json.gitignore 忽略的构建产物,分别由 @antdv-next/xbuild:token-meta(typedoc 解析源码)与 build:token-statistic(依赖 build:comp 产物做 SSR 收集)生成。docs 的 build 脚本已前置 build:token,但 docs:dev 没有,导致全新 checkout / 切分支后 component-token-table.vue import 这两个文件报错、dev 无法启动:

[plugin:vite:import-analysis] Failed to resolve import "../../assets/token-meta.json"
from "packages/docs/src/components/token/component-token-table.vue".

方案:docs:dev 的两个入口(根 package.jsonpackages/docs/package.json)前置 vp run --filter @antdv-next/x build:token,与 build 脚本保持一致。build:token 失败则 && 中止,不会带病启动。

- "docs:dev": "vp dev packages/docs",
+ "docs:dev": "vp run --filter @antdv-next/x build:token && vp dev packages/docs",
- "dev": "vp dev .",
+ "dev": "vp run --filter @antdv-next/x build:token && vp dev .",

验证: 删除两个 token 文件后执行 vp run docs:dev,确认先自动执行 build:token 重新生成 token-meta.json / token.json,随后 dev server 正常启动,无 import 报错。

代价: 每次 dev 启动多约 8s(增量)/ 15-40s(冷启动)用于构建 token,换取 token 数据始终与当前 x 源码一致。

📝 变更日志

语言 变更日志
🇺🇸 英文 Fix docs:dev failing to start on fresh checkout by generating token assets first
🇨🇳 中文 修复全新 checkout 后 docs:dev 因缺失 token 资源无法启动的问题

token-meta.json / token.json 是 gitignored 的构建产物,docs:dev 未生成它们,
全新 checkout 后 component-token-table.vue import 报错无法启动。
在 docs:dev 前置 build:token,与 docs build 脚本保持一致。
@cc-hearts cc-hearts merged commit f996292 into main Jul 10, 2026
1 check passed
@cc-hearts cc-hearts deleted the fix/docs-dev-build-token branch July 10, 2026 10:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant