airi 仓库实战VueUse useCookies 之基于 universal-cookie 的响应式 Cookie 管理【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文以 airi 仓库中.agents/skills/vueuse-functions/references/useCookies.md参考文档为主体系统讲解 VueUse 的useCookies组合式函数如何基于universal-cookie在 Vue 3 项目中以组合式 API 方式读取、写入、删除 Cookie如何通过dependencies、doNotParse、autoUpdateDependencies三个选项精确控制响应式行为以及面向 SSR 场景的createCookies(req)工厂用法。读完本文你可以在任意 Vue 3 项目包括 airi 这类基于 Vue 3 Vite 的多应用 monorepo中落地响应式 Cookie 状态管理并理解它在 airi 技能体系中的定位与依赖版本约束。useCookies 是什么定位与适用边界useCookies是 VueUsevueuse/integrations子包提供的组合式函数本质上是对universal-cookie的响应式包装Wrapper。它把universal-cookie的get/getAll/set/remove/addChangeListener/removeChangeListener这套实例方法转变成可以在 Vue 组件setup()中直接使用的组合式 API使 Cookie 的读写能够接入 Vue 的响应式系统通过dependencies声明依赖的 Cookie 名当对应 Cookie 变化时触发组件重渲染通过get/getAll获得的是响应式读取而非一次性的静态值通过cookies参数可注入自建的universal-cookie实例为 SSR服务端渲染等场景留出扩展点。在 airi 仓库中该参考文档隶属于.agents/skills/vueuse-functions/这一 AI 技能目录。该技能由 SKILL.md 定义是一份需求到 VueUse 函数的决策与实现指南其 SYNC.md 记录了该技能从上游vendor/vueuse/skills/vueuse-functions同步而来同步时间 2026-06-22。从 SKILL.md 的Integrations分类表可以看到函数描述调用规则useCookiesuniversal-cookie的包装器EXTERNALEXTERNAL规则在 SKILL.md 中有明确定义EXTERNAL仅当用户已经安装了所需的外部依赖时才使用否则应重新考虑只有在确实需要时才提示安装。也就是说useCookies不是 airi 各应用的默认基础设施——从源码结构看airi 的apps/stage-web、apps/stage-tamagotchi、apps/stage-pocket、apps/ui-server-auth、apps/component-calling等应用只声明了vueuse/core: catalog:依赖而vueuse/integrations目前是由文档站的 VitePress 传递引入的见 pnpm-lock.yaml 中 vitepress 依赖树universal-cookie仅出现在其transitivePeerDependencies列表中并未被任何应用直接安装。若你要在自己的 airi 应用中启用useCookies必须显式安装universal-cookie这个外部依赖。安装按照参考文档useCookies.md需要先安装universal-cookienpm i universal-cookie^7版本约束方面从当前仓库的锁文件可以印证兼容范围pnpm-lock.yaml 中vueuse/integrations14.4.0声明的 peerDependencies 为universal-cookie: ^7 || ^8且被标记为optional: true第 12102-12103 行。因此文档中的^7是推荐基线^8同样满足兼容要求而vueuse/integrations本体在 airi 工作区由 VitePress 2.0.0-alpha.17 以 14.4.0 版本引入。airi 工作区对 VueUse 核心包的版本统一由 pnpm-workspace.yaml 的 catalog 固定vueuse/core: ^14.4.0 vueuse/shared: ^14.4.0 vueuse/motion: ^3.0.3这提示我们在 airi 这类 pnpm workspace 中引入 VueUse 生态包时应以 catalog 锁定的 14.4.0 大版本为基准避免vueuse/integrations与vueuse/core版本错位。常见用法Common Usage参考文档给出的标准用法是一个完整的 SFC 示例监听localeCookie提供俄/英语切换按钮并以pre展示全部 Cookie。完整代码如下摘自 useCookies.mdscript setup langts import { useCookies } from vueuse/integrations/useCookies const cookies useCookies([locale]) /script template div stronglocale/strong: {{ cookies.get(locale) }} hr pre{{ cookies.getAll() }}/pre button clickcookies.set(locale, ru-RU) Russian /button button clickcookies.set(locale, en-US) English /button /div /template逐行解读useCookies([locale])的第一个参数dependencies声明了组件依赖的 Cookie 名列表。这里指定[locale]后只有locale这个 Cookie 变化才会触发重渲染若不传该参数或传null则任何 Cookie 变化都会触发重渲染若要不监听任何变化应显式传入空数组[]这一行为在类型声明的 JSDoc 中有说明Pass empty array if dont want to watch cookies changes。cookies.get(locale)是响应式读取——在模板中使用它会被收集为依赖locale变化时模板自动更新。cookies.set(locale, ru-RU)直接写入 Cookie第三参数可传CookieSetOptions如path、expires等遵循universal-cookie的 API 语义。注意导入路径vueuse/integrations/useCookies是子路径导出因此需要安装vueuse/integrations与universal-cookie两个包。解构返回值与三个核心选项参考文档useCookies.md给出了完整的解构签名import { useCookies } from vueuse/integrations/useCookies // ---cut--- const { get, getAll, set, remove, addChangeListener, removeChangeListener } useCookies([cookie-name], { doNotParse: false, autoUpdateDependencies: false })useCookies返回六个方法方法签名说明getT(name: string, options?: CookieGetOptions) T按名响应式读取 Cookie当autoUpdateDependencies true时每次调用都会把该 Cookie 名自动加入监听依赖getAllT(options?: CookieGetOptions) T响应式读取全部 Cookieset(name, value, options?: CookieSetOptions) void写入 Cookieremove(name, options?: CookieSetOptions) void删除 CookieaddChangeListener(callback: CookieChangeListener) void注册 Cookie 变化监听removeChangeListener(callback: CookieChangeListener) void移除 Cookie 变化监听文档同时提示默认应在setup()内调用但该函数在组件之外的其他地方调用也能工作。以下逐项说明三个选项的语义与默认值。dependencies第一参数可选允许你声明一个 Cookie 名列表表示组件依赖哪些 Cookie或哪些 Cookie 变化应触发重渲染。不指定时任何 Cookie 变化都会触发渲染。这是一个重要的性能考量如果你的页面只关心locale一个 Cookie就应该传[locale]避免用户环境中其他脚本频繁写 Cookie 造成无谓的重渲染。doNotParseboolean默认false含义是无论如何都不把 Cookie 值转换成对象即禁止把值尝试按 JSON 解析。该值会作为get/getAll方法的默认值传入——也就是说你在每次调用get时传入的CookieGetOptions.doNotParse若未显式指定将回退到此处设置的默认值。适合的值如语言代码ru-RU、时间戳字符串可保持原始字符串结构化值如对象则在doNotParse: false时被自动反序列化为对象。autoUpdateDependenciesboolean默认false含义是自动把任何传给get方法的 Cookie 名加入依赖列表。当设为true时你不需要关心手动提供的dependencies——只要通过get(xxx)读过的 Cookie都会自动进入监听集合响应式更新随之生效。这是一种按需自动追踪的模式适合 Cookie 名不固定或数量较多的场景。cookies第三参数可选允许你传入一个自建的universal-cookie实例不传时useCookies会默认新建一个实例基于window.document.cookie。更多universal-cookie实例方法详见其官方 API 文档Cookies Class 一节。注意若你直接传入自建实例实例的构造方式决定了它运行在浏览器端还是 Node 端——这正是下一节 SSR 场景的切入点。SSR 场景createCookies([req])参考文档useCookies.md定义了第二个导出函数createCookies(req?: IncomingMessage)作用使用请求默认是window.document.cookie创建一个universal-cookie实例并返回一个已经绑定了该实例的useCookies函数。参数reqNode.js 的http.IncomingMessage请求对象即 Node 内置 http 模块的 IncomingMessage 类实例。使用方式与工厂模式如下在 SSR 服务端渲染时Cookie 不来自浏览器document而是来自 HTTP 请求头的Cookie字段。此时可以import { createCookies } from vueuse/integrations/useCookies // 服务端用请求对象构造 const useServerCookies createCookies(req) const { get, set } useServerCookies([theme])类型声明的 JSDoc 中也明确写道useCookies用于Reactive methods to work with cookies并提示use {link createCookies} method instead if you are using SSR——即在使用 SSR 时应改用createCookies。由于universal-cookie本身支持从req中解析 Cookie这个工厂函数把 Node 侧的请求对象桥接到了 Vue 响应式层。Nuxt 3 中的注意点参考文档useCookies.md有一条重要提示在 Nuxt 3 中使用本函数时它不会被自动导入auto import以让位于 Nuxt 内置的useCookie()。如果你确实想用 VueUse 的useCookies必须显式导入。airi 仓库各前端应用如 apps/stage-web/package.json基于 Vue 3 Vite 而非 Nuxt因此不存在自动导入冲突但这条提示对任何 Nuxt 环境仍然成立useCookie()Nuxt 内置与useCookiesVueUse是两个不同实现命名相近但 API 不同混用时务必显式import { useCookies } from vueuse/integrations/useCookies避免被 Nuxt 的自动导入机制劫持成同名函数。完整类型声明以下是参考文档给出的完整 Type DeclarationsuseCookies.md可直接作为你在项目中的 API 契约参考/** * Creates a new {link useCookies} function * param req - incoming http request (for SSR) * description Creates universal-cookie instance using request (default is window.document.cookie) and returns {link useCookies} function with provided universal-cookie instance */ export declare function createCookies(req?: IncomingMessage): ( dependencies?: string[] | null, { doNotParse, autoUpdateDependencies, }?: { doNotParse?: boolean | undefined autoUpdateDependencies?: boolean | undefined }, ) { /** * Reactive get cookie by name. If **autoUpdateDependencies true** then it will update watching dependencies */ get: T any(name: string, options?: CookieGetOptions | undefined) T /** * Reactive get all cookies */ getAll: T any(options?: CookieGetOptions | undefined) T set: ( name: string, value: any, options?: CookieSetOptions | undefined, ) void remove: (name: string, options?: CookieSetOptions | undefined) void addChangeListener: (callback: CookieChangeListener) void removeChangeListener: (callback: CookieChangeListener) void } /** * Reactive methods to work with cookies (use {link createCookies} method instead if you are using SSR) * param dependencies - array of watching cookies names. Pass empty array if dont want to watch cookies changes. * param options * param options.doNotParse - dont try parse value as JSON * param options.autoUpdateDependencies - automatically update watching dependencies * param cookies - universal-cookie instance * * __NO_SIDE_EFFECTS__ */ export declare function useCookies( dependencies?: string[] | null, { doNotParse, autoUpdateDependencies, }?: { doNotParse?: boolean | undefined autoUpdateDependencies?: boolean | undefined }, cookies?: Cookie, ): { /** * Reactive get cookie by name. If **autoUpdateDependencies true** then it will update watching dependencies */ get: T any(name: string, options?: CookieGetOptions | undefined) T /** * Reactive get all cookies */ getAll: T any(options?: CookieGetOptions | undefined) T set: ( name: string, value: any, options?: CookieSetOptions | undefined, ) void remove: (name: string, options?: CookieSetOptions | undefined) void addChangeListener: (callback: CookieChangeListener) void removeChangeListener: (callback: CookieChangeListener) void }几个值得注意的类型细节createCookies的返回值是另一个useCookies工厂函数因此 SSR 场景下先createCookies(req)再调用返回值是两段式调用dependencies的类型是string[] | nullJSDoc 强调不想监听 Cookie 变化时传空数组get/getAll均为泛型T any可以按你的业务类型断言返回值例如cookies.getRecordstring, string(prefs)函数声明携带__NO_SIDE_EFFECTS__标注提示打包器该函数没有副作用可安全做 tree-shakingCookieGetOptions/CookieSetOptions/CookieChangeListener/Cookie即universal-cookie的Cookie类实例均来自universal-cookie的类型系统。在 airi 中的落地建议与限制说明结合本仓库的实际情况给出三条可验证的使用边界依赖前提useCookies属于 EXTERNAL 类函数SKILL.md 中调用规则为 EXTERNALairi 应用当前未安装universal-cookie锁文件中该包仅作为 VitePress 依赖树的可选 peer 出现见 pnpm-lock.yaml。在 airi 应用内启用前需在目标应用的package.json中同时添加vueuse/integrations与universal-cookie版本满足^7 || ^8文档推荐^7。版本一致性工作区 catalog 固定vueuse/core/vueuse/shared为^14.4.0pnpm-workspace.yaml锁文件中vueuse/integrations解析为 14.4.0 且 peer 依赖为vue: ^3.5.0。新增依赖时应保持与 catalog 一致的大版本避免 pnpm 下出现重复 VueUse 副本。SSR 限制airi 的 Web 应用stage-web、ui-server-auth 等以 Vite 构建为 CSR 为主createCookies(req)主要服务于带服务端渲染的框架环境纯客户端场景直接用useCookies即可无需工厂函数。小结useCookies把universal-cookie的 Cookie 操作封装进了 Vue 组合式 API核心设计可以归纳为三点dependencies控制监听哪些 Cookie 触发重渲染不传则全量触发空数组则完全不触发doNotParse作为get/getAll的默认解析策略控制 JSON 反序列化开关autoUpdateDependencies提供读过即监听的自动追踪模式。SSR 场景则通过createCookies(req)工厂函数把 Node 请求对象桥接为绑定实例的useCookies变体。对 airi 这类 Vue 3 monorepo 而言只要记住它的 EXTERNAL 依赖属性、按 catalog 版本14.4.0 系安装universal-cookie即可在国际化语言偏好、主题选择等需要跨会话持久化的小状态场景中获得比手写document.cookie字符串拼接更简洁、更响应式安全的实现。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
`)
`)
`)
