Vue Mixins 迁移指南：隐式合并、Composables 与状态边界

原始笔记日期为 2022-08-07；本文于 2026-10-20 按 Vue 官方文档重新整理。保留历史路径与日期，避免把旧示例误认为 Vue 3 的推荐写法。

先确认：你正在维护哪一代 Vue

Mixin（混入）把组件选项合并到使用它的组件上，常见于 Vue 2 项目，也仍受 Vue 3 的 Options API 支持。但 Vue 3 官方已不再推荐用 Mixins 复用新逻辑：属性来自哪里不够明显、多个 Mixins 容易发生命名冲突，彼此依赖也常藏在共享字段里。

维护旧项目时不必为了“现代化”一次性重写所有 Mixins。新代码或可控的小范围重构，优先根据逻辑职责选择普通函数、Composable、组件或共享状态库。

Mixins 的合并规则

组件通过 mixins: [firstMixin, secondMixin] 引入选项对象。理解合并规则有助于维护旧代码，但不应把它当成透明的“代码复制”：

Mixins 数组里的生命周期钩子会先于组件自身同名钩子执行。不要依赖隐含顺序来协调业务流程；需要协作的数据应通过参数、返回值、事件或显式服务传递。

const labelMixin = {
  methods: {
    formatLabel(value) {
      return String(value ?? '').trim();
    },
  },
};

export default {
  mixins: [labelMixin],
};

这类写法仍可用于理解或维护旧 Options API 组件。它的代价是组件直接获得了 Mixin 的方法；如果多个来源提供同名方法，最终生效者取决于选项合并规则。

Mixin 状态到底会不会共享

不能笼统地说“Mixin 的变量互不共享”。组件选项中的 data() 工厂会为每个组件实例创建并合并数据；但 Mixin 模块作用域中的变量、闭包捕获的对象、导入的单例服务仍然可能被多个实例共享。

let sharedCount = 0;

export const counterMixin = {
  data() {
    return { localCount: 0 };
  },
  methods: {
    increment() {
      this.localCount += 1;
      sharedCount += 1;
    },
  },
};

这里的 localCount 属于组件实例，sharedCount 则是模块级共享状态。若状态确实需要跨组件共享，应显式选择 Pinia 或其他状态管理方式，并定义状态所有者、更新入口和持久化边界。

新逻辑优先使用 Composable

Composable 是使用 Composition API 封装可复用有状态逻辑的函数。它显式返回调用方会使用的 refs 和函数，调用方可以重命名它们，也可以把结果传给另一个 Composable；来源和依赖因此比隐式注入更容易追踪。

import { onMounted, onUnmounted, readonly, ref } from 'vue';

export function useWindowWidth() {
  const width = ref(0);
  const updateWidth = () => {
    width.value = window.innerWidth;
  };

  onMounted(() => {
    updateWidth();
    window.addEventListener('resize', updateWidth, { passive: true });
  });

  onUnmounted(() => {
    window.removeEventListener('resize', updateWidth);
  });

  return { width: readonly(width) };
}

<script setup>
import { useWindowWidth } from './useWindowWidth.js';

const { width: viewportWidth } = useWindowWidth();
</script>

<template>
  <output>视口宽度：{{ viewportWidth }}px</output>
</template>

Composable 必须在组件的 setup() 或 <script setup> 执行上下文中同步调用，才能正确注册生命周期钩子和关联 watcher。不要在普通事件回调里临时调用它，也不要把依赖浏览器全局对象的副作用放在模块顶层；SSR 场景应在客户端生命周期中访问 window、DOM 等对象。

上例中每次调用都会创建各自的 width ref，因此每个组件实例独立监听并维护状态。如果希望多个组件共享同一状态，不要仅把 ref 移到模块级就算完成设计；应明确共享范围、清理时机、并发更新和测试策略。

按职责选择复用方式

Mixin 与 store 不是一回事：Mixin 合并组件选项，通常用于复用逻辑；store 是有意共享的应用状态容器。Composable 默认也不是全局单例，它返回什么状态、这些状态是否共享，取决于具体实现。

从旧 Mixin 渐进迁移

1. 盘点注入项。 找出每个 Mixin 的 data、方法、计算属性、watcher、生命周期和模块级变量，并记录组件实际使用的成员。
2. 拆开不同职责。 格式化、校验等无状态逻辑抽成普通函数；监听器、请求和状态同步按职责提取为 Composable；确需跨页面共享的业务状态才迁入 store。
3. 让依赖显式化。 把原本通过 this 或共享字段暗中读取的参数改为函数参数、返回值、事件或明确的服务接口。
4. 先迁一个消费者。 保持输入输出行为不变，核对模板依赖、生命周期时序、请求取消和状态所有权，再逐个迁移其他组件。
5. 覆盖冲突与清理。 测试同名选项、重复挂载/卸载、SSR、快速切换输入和异步旧响应，确认没有重复监听或状态串扰。
6. 删掉最后一个使用点后再删除 Mixin。 如果仍有组件依赖，不要提前移除或同时重写无关模块。

常见误区

• 把所有 Vue 2 Mixin 当成“全局共享状态”；组件 data() 与模块级变量的共享语义不同。
• 把每个 Mixin 都机械地改名为 useXxx；若函数不使用 Composition API，也不需要 Vue 生命周期，它可能只是普通工具函数。
• 认为 Composable 返回的普通对象会自动深度响应；需要保留响应性的值应返回 refs，调用方解构 refs 后可在模板中使用。
• 在 setup() 以外或异步回调里临时调用 Composable，导致生命周期注册时没有活动组件实例。
• 在 SSR 模块初始化时访问 window 或 document，让服务端渲染失败。
• 把前端路由、Mixin 或 Composable 当成权限边界；资源授权仍必须在服务端按身份、角色和对象逐次验证。
• 为了追求 Composition API 而整体重写稳定的旧组件；迁移应以明确的维护成本、测试收益和团队可读性为依据。

复习检查

• Vue 2 与 Vue 3 都可能出现 Mixins；阅读前先确认项目主版本和 API 风格。
• 生命周期钩子会合并执行，而对象选项可能因同名键被覆盖；不要猜测最终值。
• 组件状态、模块级状态和 store 状态的所有权不同，需要分别说明。
• 新的有状态逻辑优先使用 Composable；共享业务状态用明确的 store；纯逻辑保留普通函数。
• 每个副作用都要有清理路径；SSR 代码避免在模块顶层读取浏览器全局对象。

官方资料

• Vue：Composables 与 Mixins 的比较
• Vue：Options API 的 Mixins 选项
• Vue：组合式函数的使用限制与副作用清理
• Pinia：核心概念