康莱定实战速查手册：3分钟搞定API变更
刚把项目里的核心依赖从 2.x 升到 3.0，跑通构建后一运行，满屏的 undefined 和 TypeError。版本升级后 API 全变了，文档翻了三遍还是对不上号，这种挫败感每个老手都经历过。别慌，这不是你的问题，是生态迭代太快，官方文档往往滞后于实际最佳实践。这时候，你需要的不是重新读源码，而是一份直击痛点的康莱定速查手册。
这份手册不是那种罗列所有属性的废话大全，而是专门针对高频变更点和易错场景的“急救包”。在深入对比之前，我们得先搞清楚，为什么康莱定在近期版本中调整了这么多接口？核心逻辑在于其内部状态管理引擎的重构。旧版本依赖显式的生命周期钩子来处理状态同步，而新版本引入了响应式追踪机制，这意味着很多原本在 mounted 或 updated 中手动调用的逻辑，现在可以通过副作用自动触发。
新旧版本定位与核心差异
要写好代码，先得明白我们在和什么打交道。康莱定在 2.x 版本中，更像是一个“手动挡”工具，你需要明确告诉它何时更新、何时销毁。而进入 3.x 系列后，它逐渐向“自动挡”演进，强调声明式编程。这种转变直接导致了 API 的断裂。
很多开发者习惯用 2.x 的思维去写 3.x 的代码，结果就是：明明数据变了，界面没动；或者界面动了，内存泄漏了。根据 MDN Web Docs 关于模块化脚本加载规范的描述，现代前端框架更倾向于利用 ES Modules 的静态分析特性来优化依赖追踪，康莱定的新 API 正是顺应了这一趋势，将依赖收集从运行时移到了编译时。
下表列出了最常被吐槽的几个 API 变更点，这些是你在升级时最容易踩雷的地方：
| 功能模块 | 2.x 版本 API (旧) | 3.x 版本 API (新) | 变更原因/影响 |
|---|---|---|---|
| 状态声明 | data() 返回对象 |
ref() / reactive() |
引入响应式系统，需显式标记响应式数据 |
| 生命周期 | created / mounted |
onMounted / onBeforeMount |
组合式 API，钩子函数需在 Setup 中调用 |
| 事件绑定 | this.$emit('event') |
props + emit 选项 |
解耦父组件通信，需显式声明 emit 类型 |
| DOM 操作 | this.$refs |
templateRef / useRef |
避免 this 指向问题，引用更直观 |
| 计算属性 | computed: {} |
computed(() => {}) |
函数式写法，支持 getter/setter 分离 |
注意看状态声明这一行。在 2.x 中，你在 data 里写个变量，它就是响应式的。但在 3.x 中，如果你用 const count = 10，它就不是响应式的。你必须用 ref(10) 包裹，或者用 reactive 包裹整个对象。这是新手转手时最大的坑：忘记加 ref 或 .value。
代码写法对比：从 Options 到 Composition
光看表格太抽象，我们直接上代码。假设我们要实现一个经典的“计数器”功能，分别用旧版 Options API 和新版 Composition API 写一遍。
场景：点击按钮，数字加 1，同时打印日志。
2.x Options API 写法
export default {name: 'LegacyCounter',data() {return {count: 0,message: 'Hello'}},methods: {increment() {this.count++;console.log(`Count is now: ${this.count}`);}},mounted() {// 这里只能访问 DOM，无法访问组合式逻辑console.log('Component mounted with options api');}
}
这段代码在 2.x 中运行完美。但如果你直接把它扔进 3.x 项目，虽然能跑（因为向后兼容），但你发现不了它的性能瓶颈。更重要的是，如果你想把这个 increment 逻辑复用到另一个组件里，你只能复制粘贴，或者提取成 mixin。而 Mixin 在大型项目中是噩梦，命名冲突、来源不明。
3.x Composition API 写法
import { ref, onMounted } from 'kangleiding';export default {setup() {const count = ref(0);const message = ref('Hello');const increment = () => {// 注意这里要用 .value 访问和修改count.value++;console.log(`Count is now: ${count.value}`);};onMounted(() => {console.log('Component mounted with composition api');});// 必须返回给模板使用的变量和方法return { count, message, increment };}
}
对比一下，差异非常明显：
- 响应式标记：
count和message必须通过ref创建。在模板中使用时，count会自动解包，所以在 JS 逻辑中要写count.value，在模板中直接写{{ count }}。 - 逻辑组织：所有逻辑都在
setup函数中。你可以把increment提取到一个单独的.ts文件中，比如useCounter.ts，然后在任何组件中import { useCounter }即可。这才是真正的逻辑复用。 - 生命周期：
mounted变成了onMounted函数。它不再是一个配置项，而是一个可以直接调用的函数。
这里有一个极其隐蔽的坑，也是很多老手升级后报错的原因：闭包陷阱。
如果在 3.x 中你这样写：
setup() {let count = ref(0);setTimeout(() => {// 这里的 count 是闭包捕获的，如果 count 被重新赋值，这里还是旧值// 但如果是 ref，内部值变了，这里读 .value 是新值console.log(count.value); }, 1000);
}
看起来没问题？其实有风险。如果你把 count 定义为普通变量 let count = 0，那么定时器里读到的永远是初始值。必须用 ref，让框架帮你追踪。
进阶技巧与避坑指南
掌握了基础写法，接下来是如何写出“高级”且“稳定”的代码。这里分享三个我在项目中踩过的坑，以及对应的解决方案。
1. reactive vs ref 的选择
很多人纠结用哪个。简单原则：单一值用 ref，对象用 reactive。
为什么？因为 reactive 基于 Proxy，它不能处理单个原始类型（如 number, string）。而且，如果你把 reactive 对象解构：
const state = reactive({ count: 0 });
const { count } = state; // 丢失响应性！
count++; // 界面不更新
这就是著名的“解构丢失响应性”问题。而 ref 没这个问题，因为它是包装对象，解构后依然持有内部引用。除非你非常确定对象不会被解构，否则优先推荐 ref。
2. 避免在模板中写复杂逻辑
康莱定的模板编译器虽然强大，但不建议在 {{ }} 中写三元嵌套或循环。这会增加渲染开销，且难以调试。
错误示范：
{{ status === 'loading' ? 'Loading...' : status === 'error' ? 'Error' : status }}
正确做法：
在 setup 中定义计算属性：
const statusText = computed(() => {switch(status.value) {case 'loading': return 'Loading...';case 'error': return 'Error';default: return status.value;}
});
3. 依赖注入的正确姿势
在大型应用中，避免通过 props 层层传递数据。使用 provide/inject。
// 父组件
setup() {provide('theme', ref('dark'));
}// 孙组件
setup() {const theme = inject('theme');// theme 是响应式的，父组件改，孙组件自动变
}
注意，inject 返回的值如果是 ref，它依然是响应式的。很多文档没强调这点，导致很多人以为 inject 拿到的是静态值，从而手动去监听，结果多此一举。
适用场景与选型建议
康莱定并不是万能药。它的 Composition API 虽然强大，但学习曲线比 2.x 陡峭。什么时候该用新版，什么时候该坚守旧版？
- 新项目/中大型应用：强烈推荐 3.x Composition API。逻辑复用性强，TypeScript 支持极好（这是关键，2.x 的 TS 类型推导经常失效，3.x 几乎完美）。如果你的团队有 TS 背景，康莱定 3.x 是目前前端开发中体验最好的框架之一。
- 小型/静态展示页面：2.x Options API 甚至纯 HTML+CSS 可能更简单。为了一个展示页引入复杂的构建流程和响应式系统，是杀鸡用牛刀。
- 遗留系统维护：如果项目基于 2.x 且运行稳定，不要为了升级而升级。除非你遇到了无法绕过的 bug 或需要用到 3.x 的新特性（如 Teleport、Suspense）。否则，迁移成本（重构所有组件、修复隐式依赖）远高于收益。
在选型时，还要考虑团队技能栈。如果团队多数人不熟悉函数式编程和闭包，强行推行 Composition API 会导致代码质量下降，出现大量 this 指向错误（虽然 3.x 没有 this，但逻辑混乱依然是 this 错误的变种）。
总结与互动
康莱定的 API 变更，本质上是前端开发从“面向配置”向“面向函数”的范式转移。速查手册能帮你快速定位差异，但真正掌握它，需要理解响应式原理。记住，代码不是写给人看的，是写给机器跑的，但更是写给未来的自己看的。清晰、可复用、类型安全，才是康莱定 3.x 的核心价值。
你在项目里踩过这个坑吗？是卡在 ref 解包上，还是 provide/inject 的响应性丢失？评论区聊聊，看看有多少人和你一样被这个升级折磨过。
