Vuetify 4 仓库开发指南分支策略、命令工作流与 AI 协作编码规范【免费下载链接】vuetify Vue Component Framework项目地址: https://gitcode.com/gh_mirrors/vu/vuetify本文基于 Vuetify 仓库根目录的CLAUDE.md其内容为指向AGENTS.md的引用展开系统梳理 Vuetify 4 monorepo 的开发环境、分支策略、常用命令、贡献工作流、编码原则与代码评审规范。读完本文你将掌握在本仓库中复现问题、运行测试、执行 lint 修复、提交符合维护者预期的补丁的完整方法论并理解shallowRef/toRef默认、props 响应式下传、Sass 分层等核心工程约束背后的设计意图。一、仓库定位一个为 AI 工具链优化的 Vue 组件框架 monorepoCLAUDE.md仅有一行内容AGENTS.md——这是 Claude Code 风格的引用指令其有效内容全部沉淀在 AGENTS.md 中。AGENTS.md 的第一段话点明了仓库的根本定位Vuetify 4 component framework. Ships Material Design as the default look, but is meant to fit non-material design systems too.vuetify/v0(headless primitives) has been a direct dependency since 4.2.0 and gets adopted gradually.即Vuetify 4 以 Material Design 为默认外观但设计目标同样适配非 Material 设计系统自 4.2.0 起headless 原语包vuetify/v0已成为直接依赖并逐步被采纳下一个大版本将完全建立在它之上把设计系统拆分开来停止为每种视觉变体输出 CSS。这一架构方向解释了仓库中大量工程规范如 Keep CSS per visual variant minimal存在的深层原因。同时AGENTS.md 明确说明该文件以及.claude/目录的存在目的帮助追求快速输出的 AI 工具产出更接近维护者预期的结果降低贡献门槛。这意味着本文梳理的规范既是给人类开发者的也是给 Agent 的协作契约。仓库采用 pnpm workspace monorepo包含三个包见 pnpm-workspace.yaml 与根 package.json包职责packages/vuetifyvuetifynpm 包本体源码在src/当前版本 4.2.1见 packages/vuetify/package.jsonpackages/api-generator为文档构建 API 数据props、events、slots、描述packages/docs文档站点两个重要的外部参考文档均位于文档站源码内贡献指南packages/docs/src/pages/en/getting-started/contributing.md浏览器支持packages/docs/src/pages/en/getting-started/browser-support.md二、分支策略按变更类型选择基线AGENTS.md 给出了清晰的三分支策略表这是提交 PR 前必须做的第一项决策Base 分支用途对应文档站点master安全 bug 修复、文档vuetifyjs.comdev新 props/特性、有视觉回归风险的修复dev.vuetifyjs.comnext破坏性变更next.vuetifyjs.com选择原则与评审强相关评审清单Review rubric中专门有一条 Base branch not matching the change type (see Branches)即基线分支与变更类型不匹配会被视为真实评审发现。例如修改公共 composable 的返回形状或参数属于破坏性变更必须走next分支而非dev。三、常用命令开发、测试与 lint 的最小命令集AGENTS.md 给出了三条核心命令配合根 package.json 的 scripts 可以拼出完整开发闭环# 仓库根目录 pnpm dev # playground运行在 localhost:8090 pnpm dev docs # 文档站运行在 localhost:8095 # 在 packages/vuetify 目录内 pnpm test path # 测试单个文件或目录 pnpm lint:fix # tsgo typecheck eslint --fix从源码看这两条命令的真实行为pnpm dev实际由 scripts/dev.js 驱动它读取第一个参数若为docs则映射到vuetifyjs.com包过滤名否则默认目标为vuetify最终执行pnpm run --filter target --stream dev。也就是说pnpm dev默认启动的是packages/vuetify的开发服务器playgroundpnpm dev docs才启动文档站。根 package.json 还暴露了pnpm lint递归并行跑各包 lint、pnpm all-checks依次执行构建、lint、全部测试等组合命令是 CI 级别的完整校验入口。需要特别说明的前提条件根 package.json 中engines声明node: 24.11.1prepare脚本会执行 husky 安装、post-install.js并在非 CI 环境安装 Playwright Chromium。因此首次克隆后建议按仓库约定先pnpm install再进入开发循环。3.1 playground 与端口清理根据 .claude/skills/playground/SKILL.mdpackages/vuetify/dev/Playground.vue被 gitignorepnpm install在其缺失时会从Playground.template.vue生成pnpm dev将其服务在 localhost:8090。Vite 进程经常卡住占用 8090 端口启动前建议清理lsof -ti :8090 | xargs -r kill再pnpm dev。playground 无构建步骤/直接解析到src组件、composables、sass、工具函数的修改都会热更新所有组件含 labs自动注册。3.2 测试命令的两种运行方式.claude/skills/tests/SKILL.md 细化了测试的运行方式在packages/vuetify内pnpm test path # 同时跑 unit 与 browser 两个项目 pnpm test path --project browser # 只跑 Playwright Chromium 浏览器项目 pnpm test:open path # 有头浏览器 devtools首个失败即中止测试文件与项目对应关系*.spec.ts(x)走unitjsdom适合 composables、util 等纯逻辑*.spec.browser.tsx走browserPlaywright Chromium用于布局、焦点、键盘、overlay、滚动等需要真实 DOM 测量的场景。四、贡献工作流从复现到合入的五步循环AGENTS.md 把一次符合预期的贡献压缩为五步在 playground 复现在packages/vuetify/dev/Playground.vue中复现问题详见 .claude/skills/playground/SKILL.md改代码、观察影响改动后回到 playground 目视验证写测试除非改动微不足道trivial否则必须写测试本仓库对 trivial 的判定门槛比大多数项目更高标准见 .claude/skills/tests/SKILL.mdlint、修复、重构遵循 .claude/rules/code-readability.md考虑可访问性与 i18n/RTL这通常是实现方的责任留给框架用户处理是罕见的例外。配套的技能文档进一步明确了关键细节Playground 的使用伦理不要随意覆盖 Playground 内容除非被明确要求人类开发者可能在其中粘贴了旧用例作为关注焦点编辑时保留请求未涉及的部分。playground 示例的标准形态是暗色主题 v-containermax-width600用于小组件用d-flex flex-column ga-4纵向堆叠而非v-row/v-col开发者分屏调试时会自动换行用例要覆盖相邻组合variant、density、disabled/readonly、RTL而不只是报告的那个案例每个用例用一行简短code标签标注数据要确定、本地化、不发请求。测试的纪律bug 修复必须附带没有修复就失败的测试——先写测试看到红再修复变绿。任何非预期的console.warn/console.error都会导致测试失败预期的警告需显式断言toHaveBeenTipped()/toHaveBeenWarned()。稳定性方面用expect.poll或waitForClickable代替固定await wait(100)焦点/剪贴板操作需先取锁再释放reduced-motion 默认开启过渡相关的测试要显式调用commands.setReduceMotionDisabled()并在afterEach中恢复。五、编码原则三条贯穿全仓库的工程纲领AGENTS.md 只写了三条原则但每条都直接决定代码的 reactivity 行为值得展开shallowRef/toRef默认ref/computed仅在成本合理时使用Vuetify 4 大量采用浅响应式与派生引用避免深层响应代理的开销同时保证派生值始终跟随源头更新。向下传 props 时传递响应式源getter 或toRef而不是解包后的值这是最容易踩坑的一条。解包后的值在setup中只被读取一次、永不更新导致子组件/子 composable 拿到的是快照。详细规则见 .claude/rules/components.md// ❌ 只读一次 useTextColor(props.color) provideDefaults({ VExampleItem: { color: props.color } }) // ✅ useTextColor(() props.color) useDensity(props) provideDefaults({ VExampleItem: { color: toRef(() props.color) } })向包装组件转发 props 时用其filterPropsconst fieldProps VExampleField.filterProps(props)后再展开。Less is more, until it isnt最小补丁往往只修好了报告的那个用例却破坏或忽略了相邻的 props 组合。因此在收尾前必须扩展 playground 覆盖这些组合——这正是第 2 条工作流原则的具体落地。5.1 组件的响应式骨架useProxiedModel原则 2 的底层实现之一是useProxiedModel见 packages/vuetify/src/composables/proxiedModel.ts。从源码看它接收props、prop 名和可选的defaultValue与transformIn/transformOut内部通过getCurrentInstance(useProxiedModel)获取组件实例用ref维护内部值并通过检查vm.vnode.props上是否存在prop或 kebab-case 形式与对应的onUpdate:*监听器来判定该 v-model 是受控还是非受控。规则文档要求每个 v-model无论受控与否一律走useProxiedModel正是为了让受控/非受控两种模式的行为在框架层面统一。5.2 组件内部的其他硬性约定.claude/rules/components.md 还约束了组件骨架genericComponent会应用全局默认值与VDefaultsProvider默认值因此组件内不要再调用useDefaultsprops 工厂用propsFactory定义类型断言内联书写type: X as PropType…组件标记中禁止出现工具类d-flex、ma-2、text-center因为用户可能禁用或覆盖 utilities样式应通过组件自己的.sass实现父↔子通信用Symbol.for(vuetify:xxx)作 provide/inject key绝不使用字符串选择逻辑优先复用useGroup/useGroupItem向嵌套组件下推 props 用provideDefaults或VDefaultsProvider新增 prop 需要同时更新packages/docs/src/data/new-in.json登记propName: next minor、packages/api-generator/src/locale/en/VExample.json描述文案公共 composable 的 props 只在 composable 对应的 json 中描述一次、必要时补 docs 示例packages/docs/src/examples/v-example/prop-name.vue新组件一律从 labs 起步且 labs 组件的index.ts只能导出组件——再导出 composables、utils 或 types 会破坏 api-generator翻译 key 需要在src/locale/*.ts的每个语言文件中补充真实翻译不是英文拷贝。六、规则体系按路径作用域的编码规范AGENTS.md 规定路径作用域规则存放在.claude/rules/Claude Code 会自动加载其他工具应读取与所触及路径匹配的规则规则文件作用路径components.mdpackages/vuetify/src/components/**、src/labs/**composables.mdpackages/vuetify/src/composables/**sass.mdpackages/vuetify/src/**/*.{sass,scss}utilities.mdpackages/vuetify/src/util/**code-readability.mdpackages/vuetify/src/**6.1 共享 composables 的两种形态.claude/rules/composables.md 区分了两种形态Prop-driven 形态大多数props 工厂 接收props与组件名的use函数。签名中绝不解构 props而是通过computed/toRef内的toValue读取返回普通 ref 对象而非reactive命名加 composable 前缀如exampleClasses修饰类遵循${name}--x。Plugin 形态全局服务如 display、theme、localecreateExample(options)在 framework.ts 中调用以InjectionKey提供useExample()注入注入失败时抛出带组件名上下文的错误。其余约束需要 vm 时用getCurrentInstance(useExample)名字会进入错误信息只在激活期间存在的副作用用useToggleScope(source, fn)监听器与 observer 在onScopeDispose清理浏览器 API 用/util/globals的IN_BROWSER/SUPPORTS_*守卫。公共 API 层面composables/index.ts是公开出口内部代码必须从/composables/example精确导入而非 barrel改变公共 composable 的返回形状或参数是破坏性变更只能走next分支。6.2 Sass 与样式layer、变量、RTL 与强制色.claude/rules/sass.md 要求注意本仓库没有 stylelint以下全靠人工评审规则写在VExample.sass内包在include tools.layer(components)中让用户覆盖时不必与特异性缠斗用户可能调优的值一律用$example-*: … !default变量运行时变化或级联到子组件的值用自定义属性--v-example-*颜色取自rgb(var(--v-theme-*))绝不硬编码字面量共享 token 取自settings.$*RTL 优先逻辑属性margin-inline-start、inset-inline-end、padding-inlinetools.rtl/tools.ltr仅用于逻辑属性无法表达的变换、图标翻转、渐变forced-colors 兜底背景、阴影、overlay 在 forced-colors 模式下会消失依赖它们可见的表面/选中态/焦点/进度填充/divider 必须有media (forced-colors: active)下的边框或 outline 兜底优先currentColor/solid系统色仅在状态必须可区分时使用motion 与 reduced-motion移动/缩放类过渡需要media (prefers-reduced-motion: reduce)处理且同一条规则内禁止transition与transition-*长属性混用——最新 Vite 会将其合并成简写源码审阅看起来正常而产物 CSS 不同因此要么只用长属性transition-propertytransition-durationtransition-timing-function要么只写完整简写每个视觉变体的 CSS 保持最小优先切换自定义属性而非再生成一块修饰类——未来设计系统会丢弃 MD-only 的 CSS样式改动后由于作者看不到渲染结果必须明确告诉开发者去 Playground 检查什么受影响的 variant/density/size、暗色主题与 RTL、forced-colors 模拟、reduced-motion而不是声称看起来没问题。6.3 工具函数grep 优先、v0 优先.claude/rules/utilities.md 强调/util几乎被所有组件导入改签名即全仓波及写新 helper 前先 grephelpers.ts、dom.ts、v0.ts多数需求已存在wrapInArray、pick/omit、mergeDeep、debounce、clamp、focusableChildren、getActiveElementShadow DOM 安全用它代替document.activeElement归属约定框架管道propsFactory、defineComponent、useRender、getCurrentInstance独立成文件通用 helper 进helpers.tsDOM helper 进dom.ts环境标志进globals.ts新文件要在util/index.ts补export *类型守卫来自v0.tsisString、isNullOrUndefined等禁止裸写typeof x string或x null核心采纳 v0 helper 时要在v0.ts登记、必要时改名导出如range as createRange并删除核心副本改已有 helper 先 grep 全部调用点不要在既有名字下改变行为要么新增函数、要么在同一变更中更新所有调用者调试期裸用console.*可以甚至被鼓励lint 会拦截残留面向应用开发者的消息必须走consoleWarn、consoleError、deprecate、breaking、removed。6.4 代码可读性注释、命名与抽象.claude/rules/code-readability.md 是本仓库对 AI 生成代码最直接的过滤器默认不写注释大多数 AI 注释在复述下一行代码评审时会被删掉。只在代码无法表达原因时写一行朴素注释浏览器怪癖、顺序约束、会被简化破坏的坑。禁止复述代码、叙述意图/历史、链接 issue 或 URL那属于 commit message、给内部函数加 JSDoc。保留 import 分组头注释// Components、// Composables、// Utilities、// Types这一文件惯例。命名禁缩写短 lambda 内除外index而非idx、merged而非opts、onKeydown而非handleKeydowne事件、vm、El后缀activatorEl、contentEl等既有约定保留上下文无歧义时用单词而非短语VMenu 内open而非isMenuOpen处理器用onAction绝不用handleAction。函数优先声明式setup与模块中用function toggle () {}而非const toggle () {}。抽象原则单一调用点不抽 helper内联写新 helper 前先 grepsrc/util与src/composables不写仅改名/转发的包装用toRef/computed派生而非watch写另一个 refderive instead of syncing。七、评审清单diff 触犯即视为真实发现AGENTS.md 最后给出 Review rubric——每条在 diff 违反时都是一个真实评审发现判定细则见对应规则文件复述代码的注释或引用 issue/URL 的注释 →code-readability.md短 lambda 之外使用缩写名idx、opts、handleX→code-readability.mdprops 以解包值而非 getter/toRef下传 →components.md组件标记中出现工具类 →components.md组件index.ts导出非组件成员破坏 api-generator→components.md新 prop 缺少new-in.json条目或 api-generator 描述 →components.md在next之外修改公共 composable 的参数或返回形状 →composables.md裸写typeof/ null而不用/util守卫 →utilities.md硬编码可调值应使用!default变量、样式在tools.layer之外、能用逻辑属性却用物理left/right→sass.mdforced-colors 模式下不可见的表面或状态 →sass.md同一条规则混用transition与transition-*→sass.md非平凡改动缺测试固定wait(ms)而轮询可用基线分支与变更类型不匹配见本文第二节明确的不算发现的情形diff 未触及行中的遗留旧模式以及 PR 显式排除在外的 a11y/RTL 缺口。八、实践小结一次符合 Vuetify 预期的 AI 协作流程将以上内容串成可执行的检查单按变更类型选定基线分支master/dev/next在packages/vuetify/dev/Playground.vue复现并覆盖相邻组合按components.md骨架改代码propsFactorygenericComponentuseRenderv-model 一律useProxiedModelprops 以响应式源下传标记中不用工具类非 trivial 改动补测试unit 或 browser先红后绿避免固定wait在packages/vuetify内跑pnpm lint:fix再对照五条规则自查注释、命名、函数声明、抽象、Sass 的 layer/逻辑属性/forced-colors/motion检查 i18n/RTL 与 a11y提交时确保新 prop/组件已同步new-in.json、api-generator locale 与 docs 示例。这套规范的价值在于它把可维护性从口头约定变成了路径作用域的可查规则——改哪个目录就读哪份规则评审时每条发现都能指到具体条文。对于想为 Vuetify 4 提交高质量补丁的开发者与 AI Agent这就是仓库内的第一手操作手册。【免费下载链接】vuetify Vue Component Framework项目地址: https://gitcode.com/gh_mirrors/vu/vuetify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考