vue3-composition-pitfall-guide

准备阶段： 1. 确认项目已升级至 Vue 3 版本，检查 package.json 中 vue 依赖是否为 ^3.0.0。 2. 安装并配置 @vue/composition-api 插件（如使用 Vue 2 迁移场景）或直接使用 Vue 3 原生支持。 3. 确保开发环境支持 ES6+ 语法，推荐使用 Vite 或 Webpack 5 构建工具。 4. 准备一个测试组件文件（如 TestComponent.vue），用于实践组合式 API 功能。 执行阶段： 5. 在 <script setup> 语法块中编写组合式逻辑，替代传统的 data、methods、computed 等选项。 6. 使用 ref 或 reactive 创建响应式数据，注意 ref 需要通过 .value 访问值。 7. 将相关逻辑封装为自定义组合函数（composable），例如 useCounter、useFetch，提升复用性。 8. 在组合函数中使用 watch、watchEffect、computed 等响应式工具时，确保传入正确的响应式源。 9. 注意生命周期钩子的使用方式变化，如 onMounted、onUpdated 等需显式引入并调用。 10. 避免在 setup 或 <script setup> 中直接修改 props，应使用 emit 或 v-model 实现父子通信。 自检阶段： 11. 检查所有响应式变量是否正确声明（ref/reactive），避免出现“非响应式”更新问题。 12. 验证组合函数是否独立、无副作用，确保在不同组件中调用结果一致。 13. 使用 Vue Devtools 检查组件状态，确认响应式数据更新符合预期。 14. 运行单元测试（如 Vitest 或 Jest + Vue Test Utils），覆盖组合式逻辑的关键路径。 15. 审查代码是否符合组合式 API 最佳实践，如逻辑聚合、命名规范、类型提示（配合 TypeScript）。 落地提示： - 每次只迁移一个组件，逐步替换选项式 API。 - 建立团队内部组合式 API 编码规范，统一 composable 命名与结构。 - 记录常见“坑点”（如异步操作中的响应式丢失、watch 的 immediate 配置等），形成内部知识库。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本