vue-best-practices · Vue 3 + TypeScript 工程实践技能

技能简介

vue-best-practices 是 Skillstore 作者 hyf0 发布的 SKILL.md 格式技能，专门面向 Vue 3 + TypeScript 项目里最常见的模板类型、Volar/Vue Language Server、Vue Router 类型化、Pinia 与 CSS modules、SSR HMR 报错等问题。技能把官方文档、Issue Tracker、源码示例中分散的"修复经验"提炼为一套可被 Agent 直接消费的结构化规则，让 Claude、Codex、Claude Code 在编码、审查、重构时按统一的最佳实践生成答案。版本 v8.0.0（2026-07-04），质量评分 81（Silver 级别），主仓库位于 hyf0/vue-skills，SKILL.md 含 6 条能力描述、3 个使用场景、4 个提示词模板、3 条最佳实践与 3 条反模式，安全审计结果为 Safe——18 个文件共 1514 行静态扫描发现的命中均为 Markdown 反引号、参考示例导致的误报，未发现命令注入、提示注入、数据外泄或可执行注入。

核心能力

• Wrapper 组件与组件库的 props 类型提取：覆盖包装组件透传属性、组件库对外 API 的类型边界，整理 emit、slot、CSS module 的类型模式。
• vue-tsc 严格模板设置：给出未注册组件、缺失 data 属性、模板 attribute 等"模板类型报错"的诊断与最小修复策略。
• Volar 3 + Vue Language Server 编辑器配置：升级与配置 Volar 时需要的 IDE 设置、扩展依赖、tsconfig 选项，避免常见的类型版本错位。
• Vue Router 类型化 params 与模块解析：用 route-specific 类型替代 broad assertion，避免 as any 隐藏的真实类型错误。
• Pinia store 与 CSS modules 测试模式：覆盖 Pinia 状态单元测试、CSS module 静态解析在 Vitest/Jest 下的实践。
• SSR HMR 排错（Vite / Nuxt）：服务端渲染模式下 HMR 失灵的诊断步骤、project-local 缓存清理策略、SSR 服务端与客户端配置一致性检查。

安装配置

• 支持 Agent：Claude、Codex、Claude Code（CC），三套工作流共用同一份 SKILL.md。
• 运行环境：Vue 3.x、TypeScript 4.5+、Vite 5/Nuxt 3；技能不绑定特定 UI 库，与 Element Plus、Ant Design Vue、Vuetify、Naive UI 等均可配合。
• 外部命令依赖：SKILL.md 中示例命令（vue-tsc 类型检查、Vitest 测试、Volar CLI 检查等）经审计确认仅作为文档示例，不会被 Agent 自动执行；真正落地需要在用户审查后手动触发。
• 安装方式：通过 npx skillstore add hyf0/vue-best-practices 安装，或直接下载 SKILL.md 放入 Claude / Codex / Claude Code 的 skills 目录。
• 可选配置：建议项目根目录加 .volar/settings.json 与 tsconfig.json 的 strict 模式开关，与技能里的建议对齐。

使用步骤

1. 在 Claude / Codex / Claude Code 中加载技能 vue-best-practices，让 Agent 读取 SKILL.md 的能力清单与限制。
2. 把当前报错现象贴给技能（例如"Vue 组件在模板里报 undefined component"），让 Agent 给出"检查严格模板设置 → 检查导入范围 → 解释 vue-tsc 不可见原因 → 给出最小导入或注册修复"的四步方案。
3. 当 Vue Router 路由页面取不到 :id 参数时，请求技能输出 typed route 方案并避免宽泛断言；技能会提示 route-specific typing 才是根治方案。
4. 升级 Volar 3 或迁移到新 vue-tsc 时，让 Agent 按技能的迁移模板产出编辑器配置、tsconfig 选项、回滚方案。
5. SSR 模式 HMR 失灵时，把 Vite/Nuxt 版本、SSR 入口、客户端入口贴出来，让 Agent 走技能里的 SSR HMR 排错清单定位问题。
6. 编写组件库时，让 Agent 按 props 提取、emit 类型、CSS modules、wrapper 边界 4 项审查现有组件。

适用场景

• Vue 3 + TS 工程基线：新接手 Vue 3 + TypeScript 项目的工程师，需要一份覆盖模板类型、Volar、Vue Router、Pinia 的工程实践基线。
• 严格模板类型报错：遇到"模板里找不到组件""template attribute 类型缺失"等典型 vue-tsc 报错，需要快速定位最小修复。
• Volar / Vue Language Server 升级：从 Volar 2 升级到 Volar 3 或从 vue-tsc 1 升级到 2 时，需要结构化的升级 + 回滚指南。
• 组件库对外 API 类型化：开发团队组件库对外暴露 wrapper 组件，需要梳理 props 提取、emit 类型、CSS module 的类型边界。
• SSR 项目 HMR 排错：Vite SSR / Nuxt 3 SSR 模式下修改 script setup 导致 HMR 失灵，需要按系统化步骤排错。

适用人群

• 使用 Vue 3 + TypeScript 开发业务系统的前端工程师
• 维护或开发 Vue 组件库的技术负责人
• 采用 Claude / Codex / Claude Code 进行 Vue 项目 AI 辅助开发的工程师
• 排查 vue-tsc / Volar / Vue Router 模板类型报错的开发者
• 把 Vue 3 工程从 Options API 升级到 Composition API + TS 的迁移工程师

工作原理

技能是一份面向 Agent 的结构化提示工程文件，由作者 hyf0 从多年 Vue 3 + TypeScript 项目维护经验中沉淀。它把官方文档、Issue Tracker、源码示例里零散的"修复经验"组织成"能力清单 + 使用场景 + 提示词模板 + 反模式"的指令模板。Agent 加载 SKILL.md 后，按场景模板逐项诊断当前问题，从 props 提取、vue-tsc 设置、Volar 配置、Vue Router 类型化、Pinia 测试、SSR HMR 排错等维度输出结构化修复方案。技能本身不执行命令，而是把决策依据编码到提示词中，让开发者拿到的不是一段不透明的代码生成，而是有据可查的工程建议。

官方链接

• 技能主页：https://skillstore.io/skills/hyf0-vue-best-practices
• 安全审计报告（v4）：https://skillstore.io/skills/hyf0-vue-best-practices/audits/4
• SKILL.md Markdown：https://skillstore.io/skills/hyf0-vue-best-practices.md
• 作者仓库：https://github.com/hyf0/vue-skills
• Vue 3 官方文档：https://cn.vuejs.org/
• Volar 仓库：https://github.com/vuejs/language-tools
• Skillstore 平台：https://skillstore.io/

出品方与版本

• 作者：hyf0
• 版本：v8.0.0（内容修订 r1）
• 首发日期：2026-07-04
• 审计版本：Audit v4（Safe）
• 许可协议：MIT License