vue-pinia-best-practices

vue-pinia-best-practices 技能概览

vue-pinia-best-practices 是一个面向 Vue 3 团队的专项指导技能，适合正在使用 Pinia、希望减少状态管理 bug，并在架构默认决策上更稳妥的场景。它不是泛泛而谈的 Vue 教程，而是专注解决真实项目里最容易浪费时间的 Pinia 问题：安装时机不对、解构导致响应式失效、setup store 在 SSR/DevTools 下表现异常，以及哪些状态该放进 store、哪些更适合放进 URL。

哪些人最适合使用这个技能

这个 vue-pinia-best-practices 技能尤其适合：

• 已经在使用或准备采用 Pinia 的 Vue 3 开发者
• 正在从 Vuex 或手写 reactive() store 迁移的团队
• 遇到 getActivePinia() 等具体运行时问题的开发者
• 希望建立可扩展约定、而不是只够小项目使用的前端工程师

如果你的应用存在共享状态、路由联动、SSR、DevTools 调试流程，或者多人协作开发，这个技能会特别有价值。

它能帮你完成什么任务

当你希望 AI 助手审查或生成 Pinia 代码，并尽量避开那些隐蔽但高频的坑时，就该用 vue-pinia-best-practices。它真正要解决的不是“给我讲讲 Pinia”，而是“帮我把 store 结构设计对，在上线前规避那些已知的常见错误”。

它和普通 Vue 提示词有什么不同

普通提示词也许能生成“看起来没问题”的 Pinia 代码，但在真实项目里依然可能出错。vue-pinia-best-practices 更强的地方在于，它围绕一组高影响、且有明确经验依据的模式展开：

• 在任何会消费 store 的逻辑之前先安装 Pinia
• 避免在应用初始化之前于顶层访问 store
• setup store 中要返回所有响应式状态
• 解构 state 和 getter 时使用 storeToRefs()
• 可分享的筛选状态应放进 URL，而不是只放在 Pinia 里
• 在规模更大的应用中，优先选择 Pinia，而不是临时拼出来的 ad hoc store

它不打算覆盖哪些内容

这个技能是刻意收窄范围的，它不能替代以下内容的完整官方文档或深入资料：

• 高级插件编写
• SSR 框架端到端集成的全部细节
• 所有可能的 store 组织风格
• 与 Pinia 无关的 Vue 组件模式

如果你需要的是非常完整、且强依赖具体框架的配置方案，应把这个技能视为“防踩坑护栏”，而不是完整实施方案本身。

如何使用 vue-pinia-best-practices 技能

vue-pinia-best-practices 的安装上下文

如果你的 skill runner 支持基于仓库安装技能，可以像安装同一集合里的其他技能一样，从 vuejs-ai/skills 添加 vue-pinia-best-practices。安装后，最重要的工作目录是：

• skills/vue-pinia-best-practices/

建议先看：

• SKILL.md

然后再根据你当前遇到的问题，阅读对应的参考文件。

按问题类型优先阅读这些文件

最快的方式，是直接打开和症状相匹配的参考文件：

• reference/pinia-no-active-pinia-error.md：处理启动期 / 安装顺序导致的崩溃
• reference/pinia-setup-store-return-all-state.md：处理 setup store 在 SSR 或 DevTools 下的问题
• reference/pinia-store-destructuring-breaks-reactivity.md：处理解构后 UI 不再更新的问题
• reference/state-url-for-ephemeral-filters.md：处理筛选、搜索、排序、分页等状态
• reference/state-use-pinia-for-large-apps.md：处理架构决策
• reference/store-method-binding-parentheses.md：处理非 Pinia 响应式 store 中的方法绑定问题

这个 repo 体量不大，所以比起从头线性读完，尽早找到对口文件更重要。

这个技能要拿到哪些输入，才能帮得更准

vue-pinia-best-practices 在你提供具体实现上下文时效果最好，而不是只说一句“帮我看看 Pinia”。建议至少带上这些信息：

• 你的 Vue 版本，以及是否使用 Vue 3 + Composition API
• 这是 Pinia store，还是手写的 reactive store
• 问题出现在启动时、路由跳转时、模板渲染中，还是刷新之后
• 相关文件，例如 main.ts、router 配置、一个 store 文件、一个消费它的组件
• 是否涉及 SSR、DevTools 可见性、URL 持久化

如果缺少这些背景，助手给出的建议可能 technically 没错，但和你的实际问题对不上。

如何把模糊需求改写成高质量提示词

较弱的提示词：

• “Help me fix my Pinia store.”

更好的提示词：

• “Use the vue-pinia-best-practices skill. I have a Vue 3 app with Pinia and Vue Router. I get getActivePinia() during startup when a router guard reads useAuthStore(). Review my main.ts and router file, explain the root cause, and rewrite the setup in the safest order.”

另一个高质量示例：

• “Use vue-pinia-best-practices to review this setup store for SSR and DevTools compatibility. Tell me if any reactive state is not returned, what that breaks, and provide a corrected store.”

vue-pinia-best-practices 的实用工作流

这个技能比较可靠的使用方式通常是：

1. 先判断症状属于哪一类：启动、响应式、setup store 结构、URL 状态，还是架构问题。
2. 提供能最小复现问题的一组文件。
3. 让助手结合对应的 reference/*.md 文件进行诊断。
4. 要求输出修正后的代码，并附上一条可复用的简短规则。
5. 第一轮修复后，再让它给出一个检查清单，用于在整个 repo 中推广同样的模式。

这种做法通常比“不带代码直接来一轮 best practices review”效果更好。

用它定位启动期和插件顺序 bug

vue-pinia-best-practices 最有价值的用途之一，就是解决 “no active Pinia” 这类故障。如果 router guard 或某些模块过早调用了 store，可以让助手重点检查：

• main.js 或 main.ts
• router 的创建方式和 guard 注册顺序
• 任何在顶层 import 后就调用 `useXxxStore()`` 的代码

关键问题通常不在 store 实现本身，而在初始化时机。

用它检查不会破坏响应式的解构方式

如果你从 store 中取值后，UI 就不再更新，可以让这个技能检查你是否直接解构了 store。大概率正确的修正方向是：

• actions 如有需要，可以直接解构
• state 和 getters 应通过 storeToRefs() 处理后再解构

对于任何读取多个 store 值的组件，这都是很值得做的一次 review。

用它检查 setup store 的 SSR 和 DevTools 兼容性

如果你使用的是 defineStore('x', () => {})，可以让助手核对是否返回了所有响应式状态。因为一旦有状态没返回，往往会静默破坏这些能力：

• SSR 序列化与 hydration
• Vue DevTools 检查能力
• Pinia 插件兼容性

这也是为什么 vue-pinia-best-practices 很适合用于 code review，而不只是出了 bug 之后再来排查。

用它判断状态应该放在哪里

vue-pinia-best-practices guide 还有一个容易被低估、但很有价值的用途：判断某些数据到底该不该放进 Pinia。你可以让助手把状态分成几类：

• 应用级共享状态
• 组件局部状态
• 由 URL 承载的视图状态，例如筛选、搜索、分页和排序

这正是它比通用 Pinia 代码片段更有价值的地方：它帮助你在代码膨胀之前，先避免走向错误架构。

做仓库审查时的最佳提示词模式

如果你想把 vue-pinia-best-practices for Frontend Development 用在仓库审查上，一个高质量的审计提示词可以是这样：

• “Use the vue-pinia-best-practices skill to audit these files for Pinia gotchas. For each issue, label it as install timing, reactivity, setup-store return shape, or state-placement mistake. Show exact fixes and explain production impact.”

这种表述方式会推动模型输出可执行的问题清单，而不是抽象空泛的建议。

vue-pinia-best-practices 技能常见问题

vue-pinia-best-practices 适合初学者吗？

适合，但前提是你已经开始用 Vue 3 开发，并且已经接触过 Pinia。这个技能内容精炼、以问题为中心，通常比大而全的文档更容易直接上手。不过如果你是完全零基础，仍然可能需要先看官方 Pinia 基础文档，补齐 store、getter、action 等概念。

vue-pinia-best-practices 最擅长解决哪些问题？

它最强的，是少数几类高频且影响很大的问题：

• getActivePinia() 这类初始化时机错误
• 直接解构导致的响应式失效
• setup store 没有返回全部状态
• 判断 URL query state 何时优于 store state
• 判断 Pinia 何时比手写状态管理更值得使用

这比普通的 Pinia 求助更好吗？

对于这些特定主题，通常是的。普通提示词经常会生成表面合理、但忽略运行时细节的代码，比如插件顺序、SSR 序列化，或 storeToRefs() 的正确使用。vue-pinia-best-practices skill 的价值就在于，它把模型的注意力收束到那些经过验证的高频坑点和修正模式上。

什么情况下不该用 vue-pinia-best-practices？

如果你的任务主要是下面这些，就不太适合：

• 从零开始学习 Vue
• 与 Pinia 无关、但强依赖框架的部署配置
• 超出本 repo 覆盖范围的高级状态机设计
• 非 Vue 技术栈的前端项目

它是一个聚焦 Pinia 的防踩坑技能，不是通用型前端架构顾问。

它能帮助做 Vuex 迁移决策吗？

可以，虽然是间接帮助。这个 repo 明确支持这样的判断：对于更大的 Vue 应用，Pinia 是更合理的默认选择，而 Vuex 已处于 maintenance mode。它尤其适合帮助团队把旧的 Vuex 使用习惯，重构成当前更符合 Pinia 的实践方式，比如更简洁的 store 使用方式和工具链体验。

vue-pinia-best-practices 也能处理手写 store 吗？

部分可以。仓库里有一个参考文件专门讲 reactive store 中的方法绑定陷阱，这个技能也能帮助你判断手写状态管理在什么情况下仍然可以接受。但它的重心始终还是 Pinia，而不是自定义 store 库。

如何提升 vue-pinia-best-practices 技能的使用效果

给出精确的故障症状

如果你想让 vue-pinia-best-practices 输出更高质量，最好把报错原文、出现位置，以及问题是从什么时候开始的都说清楚。例如：

• “Error occurs only during router navigation”
• “DevTools does not show a ref from my setup store”
• “UI stops updating after destructuring the store in <script setup>”

这些线索都能直接映射到 repo 中最强的那几条指导。

说明生命周期阶段和文件边界

很多 Pinia bug，本质上其实都是时机问题。要告诉助手，相关代码到底运行在什么阶段：

• 模块 import 时
• setup() 中
• router guard 中
• 应用启动阶段
• SSR hydration 期间

有了这些上下文，这个技能才能区分“安装顺序问题”和“普通组件 bug”。

提供尽量小、但信息完整的代码切片

通常更好的输入会包括：

• main.ts
• 如果 guard 使用了 store，则提供一个 router 文件
• 一个 store 文件
• 一个消费该 store 的组件

不要一上来就把整个 repo 全贴进去。更紧凑的复现材料，往往能让诊断更快，也更少出现空泛套话。

不要只要修复，也要它先做分类

一个高产出的提示词是：

• “Classify each issue by category, explain why it happens, then patch the code.”

对于这个技能，比较有用的分类包括：

• install timing
• reactivity
• setup-store return shape
• URL vs store state
• scale/architecture fit

这样得到的输出不只解决当前文件，也更容易复用到后续代码里。

要求提供前后对照代码

相比 vue-pinia-best-practices install 这一步，真正关键的问题其实是：它能不能实实在在改善你生成或维护的代码？最好的判断方式，是直接要求它给出：

• 修正后的代码示例
• 原始写法为什么会失败的简短说明
• 一份可以迁移到其他文件的检查清单

这样这个技能就不再只是一次性问答，而会变成可重复使用的审查工具。

留意这些常见失败模式

当输入信息过少时，最容易得到质量偏弱的输出。常见情况包括：

• 只说“求 best practices”，但没有任何代码或症状
• 没说明 store 是 option-style 还是 setup-style
• 明明是启动问题，却没贴 router 配置
• 提到了筛选状态持久化，却没说明是否需要可分享 URL

遇到这种情况时，助手给出的建议可能是对的，但并不能真正解决你的问题。

第一轮输出后继续追问

拿到第一轮答案后，建议继续追问第二轮，例如：

• “Now scan for the same pattern in the rest of my stores.”
• “Convert this fix into a team convention.”
• “Show how this changes if the state should be shareable by URL.”
• “Add SSR and DevTools checks to the review.”

这是让 vue-pinia-best-practices usage 发挥更大价值的最简单方式，比只拿一次修复结果要更划算。

把参考文件转成代码审查规则

这些参考文件都比较短小，很适合直接提炼成团队 code review 检查项。例如：

• 不要在模块顶层调用 useXxxStore()
• 如果 router guard 要读 store，就先安装 Pinia 再安装 router
• setup store 必须返回所有响应式状态
• 解构 state/getter 时使用 storeToRefs()
• 如果筛选条件需要支持刷新后保留或链接分享，就把它放进 URL

从长期看，这才是提升 vue-pinia-best-practices for Frontend Development 使用效果的最佳方式：不要等 bug 出现后再修，而是把它变成团队默认遵守的规则。