pinia-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vuejs/pinia

pinia

vuejs/pinia

pinia

Version: 3.0.4 (Nov 2025) Deps: @vue/devtools-api@^7.7.7 Tags: next: 2.0.0-rc.10 (Sep 2021), beta: 2.1.8-beta.0 (Apr 2024), latest: 3.0.4 (Nov 2025)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

**版本：**3.0.4（2025年11月） 依赖：@vue/devtools-api@^7.7.7 **标签：**next: 2.0.0-rc.10（2021年9月），beta: 2.1.8-beta.0（2024年4月），latest: 3.0.4（2025年11月）

参考链接：文档 — API参考、使用指南 • GitHub Issues — 问题反馈、解决方案、边缘案例 • GitHub Discussions — 问答、模式、实践方案 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes — prioritize recent major/minor releases.

BREAKING:
```
defineStore({ id: 'storeName', ... })
```
— object signature with
```
id
```
property removed in v3.0.0; use
```
defineStore('storeName', { ... })
```
instead. Old object syntax silently compiled but is now a runtime error source
BREAKING:
```
PiniaStorePlugin
```
type — removed in v3.0.0; use
```
PiniaPlugin
```
instead. Code using
```
PiniaStorePlugin
```
will fail to compile source
BREAKING: Vue 2 support dropped in v3.0.0 — Pinia v3 requires Vue 3 only. Users on Vue 2 must stay on Pinia v2 source
BREAKING: TypeScript 5 or newer required in v3.0.0 — uses native
```
Awaited
```
type introduced in TS 4.5; TS 5+ recommended source
BREAKING: IIFE bundle no longer bundles Vue Devtools in v3.0.0 — devtools API was too large; must be included manually depending on your workflow source
BREAKING: Package is now published as
```
type: module
```
in v3.0.0 — CJS dist files still provided but the package root is ESM. May break setups relying on implicit CJS resolution source
NEW:
```
action(fn, name?)
```
helper in setup stores — added in v2.2.0, available via
```
SetupStoreHelpers
```
parameter. Wraps a function so it is tracked by
```
$onAction
```
when called within the store; intended for advanced use cases like Pinia Colada source
NEW:
```
disposePinia(pinia)
```
— added in v2.1.7, stops the pinia effect scope and removes state, plugins, and stores. Useful in tests or multi-pinia apps; disposed instance cannot be reused source
NEW:
```
SetupStoreDefinition<Id, SS>
```
type — added in v2.1.7 for the return type of
```
defineStore()
```
when using a setup function. Extends
```
StoreDefinition
```
and enables better IDE support for setup stores source
NEW:
```
mapWritableState
```
now picks up writable
```
computed
```
s in setup stores — added in v2.3.0. Previously only
```
ref
```
state was mapped;
```
WritableComputedRef
```
returns from setup stores are now included source

Also changed:

mapGetters

DEPRECATED (alias for

mapState

, still exported) ·

getActivePinia()

returns

Pinia | undefined

(typed more strictly since v2.0.35) ·

skipHydrate(obj)

stable — skips SSR hydration for non-state objects returned from setup stores ·

shouldHydrate(obj)

exported utility for plugin authors

本节记录特定版本的API变更 — 优先关注近期的主版本/次版本更新。

破坏性变更：
```
defineStore({ id: 'storeName', ... })
```
— 带
```
id
```
属性的对象签名在v3.0.0中已移除；请改用
```
defineStore('storeName', { ... })
```
。旧的对象语法之前会静默编译，但现在会触发运行时错误来源
破坏性变更：
```
PiniaStorePlugin
```
类型 — 在v3.0.0中已移除；请改用
```
PiniaPlugin
```
。使用
```
PiniaStorePlugin
```
的代码将无法编译来源
破坏性变更：v3.0.0中移除了Vue 2支持 — Pinia v3仅兼容Vue 3。使用Vue 2的用户必须停留在Pinia v2版本来源
破坏性变更：v3.0.0要求使用TypeScript 5或更高版本 — 使用了TS 4.5引入的原生
```
Awaited
```
类型；推荐使用TS 5+ 来源
破坏性变更：v3.0.0中的IIFE包不再捆绑Vue Devtools — Devtools API体积过大；需根据你的工作流手动引入来源
破坏性变更：v3.0.0中包以
```
type: module
```
形式发布 — 仍提供CJS分发文件，但包根目录为ESM。可能会破坏依赖隐式CJS解析的配置来源
新增：setup store中的
```
action(fn, name?)
```
工具函数 — 在v2.2.0中添加，可通过
```
SetupStoreHelpers
```
参数获取。用于包装函数，使其在store内部调用时能被
```
$onAction
```
追踪；适用于Pinia Colada等高级场景来源
新增：
```
disposePinia(pinia)
```
— 在v2.1.7中添加，用于停止pinia的作用域并移除状态、插件和store。在测试或多pinia应用中非常实用；已销毁的实例无法重复使用来源
新增：
```
SetupStoreDefinition<Id, SS>
```
类型 — 在v2.1.7中添加，作为使用setup函数时
```
defineStore()
```
的返回类型。扩展了
```
StoreDefinition
```
，为setup store提供更好的IDE支持来源
新增：v2.3.0中
```
mapWritableState
```
现在可识别setup store中的可写
```
computed
```
— 之前仅能映射
```
ref
```
状态；现在setup store返回的
```
WritableComputedRef
```
也会被包含在内来源

其他变更：

mapGetters

已废弃（作为

mapState

的别名，仍会导出）·

getActivePinia()

Pinia | undefined

（自v2.0.35起类型更严格）·

skipHydrate(obj)

已稳定 — 用于跳过setup store返回的非状态对象的SSR hydration · 为插件作者导出了工具函数

shouldHydrate(obj)

Best Practices

最佳实践

Use
```
$patch()
```
with a function callback rather than an object when mutating arrays or performing multiple related changes — the function form groups all mutations into a single devtools entry and avoids creating intermediate collections source
Use
```
$subscribe()
```
instead of
```
watch()
```
on store state — subscriptions fire only once per
```
$patch
```
call regardless of how many individual properties changed, avoiding redundant callbacks when using the function form of
```
$patch
```
source
Pass
```
{ detached: true }
```
to
```
$subscribe()
```
and
```
true
```
as the second arg to
```
$onAction()
```
when you need listeners to outlive the component — by default both are automatically removed on component unmount source
In setup stores, use
```
skipHydrate()
```
to wrap state properties that must not be picked up from SSR initial state (e.g., composables backed by
```
localStorage
```
, client-only refs) — without it, the server's serialized value will override the intended client-side source source

return {
  lastColor: skipHydrate(lastColor), // won't be overwritten by SSR state
  open,
}

When a plugin adds new state properties, set the value on both
```
store.$state
```
(for SSR serialization and devtools) and
```
store
```
via
```
toRef(store.$state, 'key')
```
— setting only one breaks devtools display or reactivity sharing source
Wrap non-reactive external objects (router, class instances, third-party lib instances) with
```
markRaw()
```
before assigning them in plugins — prevents Vue from trying to deeply observe objects that aren't meant to be reactive source
When composing stores that reference each other, place
```
useOtherStore()
```
calls before any
```
await
```
in async actions — after an
```
await
```
the active pinia context may have changed, causing the wrong instance to be returned in SSR source
Use
```
createTestingPinia()
```
from
```
@pinia/testing
```
for component tests rather than
```
createPinia()
```
— it stubs all actions by default and makes them inspectable as spies; pass plugins via the
```
plugins
```
option, not via
```
testingPinia.use()
```
source
In options store getters, prefer arrow functions that receive
```
state
```
as the first parameter over regular functions using
```
this
```
— arrow function return types are inferred automatically, while
```
this
```
-based getters require an explicit return type annotation source

当修改数组或执行多个相关变更时，优先使用带函数回调的
```
$patch()
```
而非对象形式 — 函数形式会将所有变更合并为一个devtools条目，避免创建中间集合来源
优先使用
```
$subscribe()
```
而非
```
watch()
```
监听store状态 — 无论有多少个属性变更，订阅仅会在每次
```
$patch
```
调用时触发一次，避免使用函数形式
```
$patch
```
时出现冗余回调来源
当需要监听器在组件销毁后仍保持生效时，给
```
$subscribe()
```
传入
```
{ detached: true }
```
，给
```
$onAction()
```
的第二个参数传入
```
true
```
— 默认情况下，两者都会在组件卸载时自动移除来源
在setup store中，使用
```
skipHydrate()
```
包装不需要从SSR初始状态获取的状态属性（例如基于
```
localStorage
```
的composable、仅客户端的ref） — 若不使用该函数，服务器的序列化值会覆盖预期的客户端数据源来源

return {
  lastColor: skipHydrate(lastColor), // won't be overwritten by SSR state
  open,
}

当插件添加新的状态属性时，需同时在
```
store.$state
```
（用于SSR序列化和devtools）和通过
```
toRef(store.$state, 'key')
```
在
```
store
```
上设置值 — 仅设置其中一个会破坏devtools显示或响应式共享来源
在插件中分配非响应式外部对象（路由、类实例、第三方库实例）前，先用
```
markRaw()
```
包装 — 避免Vue尝试深度观察非响应式对象来源
当组合相互引用的store时，在异步action中的任何
```
await
```
之前调用
```
useOtherStore()
```
—
```
await
```
之后活跃的pinia上下文可能会改变，导致在SSR中返回错误的实例来源
组件测试中使用
```
@pinia/testing
```
中的
```
createTestingPinia()
```
而非
```
createPinia()
```
— 它会默认存根所有action，并将其作为可检查的间谍；通过
```
plugins
```
选项传入插件，而非
```
testingPinia.use()
```
来源
在options store的getter中，优先使用以
```
state
```
为第一个参数的箭头函数而非使用
```
this
```
的普通函数 — 箭头函数的返回类型会被自动推断，而基于
```
this
```
的getter需要显式的返回类型注解来源