Vue3+AI开发：Skills技能包实战与高频避坑指南

直接说结论：Vue3 配上 AI 工具，用好了是真省事，用不好就是灾难现场。最近我把自己在 Vue3 项目里跟 AI 辅助编码摸爬滚打的经验沉淀成了一套可复用的 Skills 技能包，顺便把那些反反复复踩到的坑也整理成了避坑指南。这篇文章就是把这套东西完完整整拆给你看，包括 Skills 的设计思路、实际用法、Vue3 环境里高频踩坑的根因分析和排查模板，全程都是实操过的内容，不整虚的。适合正在用 Vue3 做管理系统、商城、后台类项目的朋友，也适合那些被 AI 代码生成搞到头大的前端。

1. 先搞清楚：Skills 在 Vue3 开发里到底解决什么问题

1.1 为什么普通提示词不够用

很多人用 AI 写代码，第一反应是“帮我写个 Vue3 后台管理系统”，然后把需求敲进去，等 AI 吐出来一坨代码。结果往往很真实：组件语法看着像 Vue2，选项式 API 和组合式 API 混着用，ts 类型 check 不过，或者干脆用了某个已经废弃的 API。这不是 AI 蠢，而是你给它的上下文太贫瘠了。

大模型本身是个“高智商但没常识”的实习生，它学过海量代码，但你项目里的 Node 版本、Vue 版本、tsconfig 配置、构建工具链、UI 组件库、代码规范它一概不知。普通提示词就像你对着一个刚入职的同事喊了句“把那个页面改一下”，他要是能做对才有鬼。而 Skills 解决的问题，本质上就是“把项目里沉淀出来的经验、约束、规范打包成一个可加载的结构化上下文”，让 AI 在动手之前先拿到一份完整的“项目宪法”。

我自己最早是从 Claude 的 Skills 和 Codex 的 skills 功能开始尝试的。后来发现，与其等各个工具厂把 Skills 生态做统一，不如自己先定义一个适合 Vue3 项目的技能包结构，配合不同工具去用。结果意外地稳，AI 生成代码的一次性通过率明显高了，特别是 vue3 + ts + vite 这种组合，原来改类型报错能来回拉扯三四轮，现在基本一轮就能给出靠谱答案。

1.2 我给 Vue3 项目定制的 Skills“三层结构”

我自己的 Vue3 Skills 技能包不是随便写几个指令就完事，它分三层，每一层管的事情不一样。拿它来配我的后台管理系统和商城项目，效果都非常好。

第一层是项目元信息与版本约束。这里写清楚项目的 Node 版本要求、包管理器（pnpm/npm/yarn）、Vue 版本（3.4.x 还是 3.5.x）、是否用了 TypeScript 严格模式、构建工具是 Vite 还是 Webpack、UI 组件库是 Element Plus 还是 Naive UI，还有是否用了 uniapp 这类跨端方案。这些东西看起来琐碎，但 AI 在选 API 和写法时全靠它们做判断。比如你不告诉它项目用了 Vite，它可能就给你生成一套基于 webpack 的别名配置。

第二层是避坑规则集。这一层是把自己在项目里踩过的坑、团队代码规范、框架层面的约束都写成“如果遇到 X，就用 Y，不要用 Z”的规则。比如“遇到 Element Plus 的 el-tabs 修改样式，必须用 :deep() 且不要加 scoped 之外的全局样式”，“在 Vue3 里避免使用 Vue2 风格的 filter”，“不要在 setup 之外访问 getCurrentInstance”等等。AI 拿到这些规则，相当于背着参考答案进考场。

第三层是输入输出格式。简单说，就是告诉 AI 该按照什么样的格式返回结果。比如遇到 ts 报错时，要求它先给出报错原因分析，再给出修改后的完整代码块，最后附上可能影响到的文件清单。这个格式约束非常重要，因为 AI 默认喜欢直接甩一段代码，但复杂项目里改一个文件往往牵扯到其他文件，如果它不说明影响范围，你这个改动就埋雷了。

这三层结构其实就是把“人的经验”翻译成“机器的上下文”，比你在对话里临时贴十个文件要高效得多。

2. 常用工具选型与真实使用场景拆解

2.1 哪些 AI 工具适合配合 Vue3 开发

现在市面上的 AI 编程工具不少，但每一类的定位不一样，我的个人建议是不要一把梭，不同场景用不同工具。我长期用的主要有四类：对话式大模型、IDE 插件、CLI Agent、本地部署模型。四者在 Vue3 开发里的表现差异挺大的。

先说说对话式大模型，代表就是 Claude 和 GPT 这类。它们的强项是理解复杂问题、做方案设计，比如“我这个 vue3 后台管理系统的权限路由应该怎么设计”，这类偏架构和思路的问题，对话式模型表现最好。但你要是让它直接改项目里的某个文件，它没有上下文，只能靠猜。

IDE 插件这一类的代表是 GitHub Copilot 和 Cursor 内置的自动补全。它们最擅长的是“接着你当前代码往下写”，写模板、写样式、写简单的逻辑片段特别顺手。但问题在于它们很少主动提醒你“这个写法有坑”，因为它们的上下文集中在当前文件，项目级约束感知较弱。

CLI Agent 这一类，比如 Codex CLI 和 Codebuddy，优势是直接操作文件、运行命令、读项目结构。对我这种追求效率的人来说，这类工具最适合做“批量改动”和“脚手架生成”。但要注意，它的自由度越高，风险越大，必须有版本控制兜底。

本地部署模型就比较特殊了，适合公司有代码保密要求、不能把业务代码发给云端 API 的场景。目前开源模型做简单代码补全和基础问答问题不大，但处理 vue3 + ts 的复杂类型推导时还是容易“翻车”，需要把 Skills 写得非常细致才勉强能用。

2.2 实测：用 Skills 给 AI“上课”处理 vue3 ts 报错

拿一个很经典的场景来说：若依（RuoYi）的 Vue3 + TS 版本，很多同学拿下来跑起来之后，改代码时经常遇到一坨 TS 报错。我之前一度被“对象的类型为 unknown”和“类型 X 上不存在属性 Y”这种问题折磨到怀疑人生。后来我自己写了一个针对这种项目的 Skill，叫“vue3-ts-error-fixer”，效果立竿见影。

这个 Skill 的核心指令是这样的：

你是一个 Vue3 + TypeScript 严格模式下的错误诊断专家。项目使用 Vite 构建，Node 版本 18+，UI 组件库为 Element Plus。 当你收到一个 TS 报错时，必须按照以下步骤处理： 1. 先定位报错文件的导入语句，查看是否是类型未正确导入。 2. 如果是 "类型 X 上不存在属性 Y"，优先检查是否缺少泛型约束，而不是急着用 any。 3. 如果根因涉及组件 props/emits 类型定义，给出 defineProps 和 defineEmits 的类型补充方案。 4. 返回格式必须为：报错原因 -> 涉及文件 -> 修改后的代码块 -> 受影响的其他文件。

我把这个 Skill 放到 Codex CLI 里跑了一下，果然稳了。举个例子，某个列表页面里用了reactive定义一个搜索表单，然后给一个自定义组件传值，AI 一开始绞尽脑汁想要怎么把类型给“糊弄”过去。加了 Skill 之后，它会主动检查这个表单的类型声明，然后指出searchForm缺少interface定义，最后给出一个完整的interface SearchForm定义方案。这就是 Skills 的价值——它把 AI 从“代码生成器”升级成了“懂项目规则的助手”。

2.3 无干扰的编码体验是怎么养成的

还有一个容易被忽略的点：频繁切换工具本身就是在打断心流。AI 工具再多，也不建议一个对话框开三个。我的习惯是：写代码阶段只开 IDE 插件，做大规模重构或排查报错的时候才启动 CLI Agent，方案设计阶段用对话式模型。而且每次用完一个工具，就把这次对话里有效的部分提炼成一条规则，补充到 Skills 包里。

这个习惯坚持了两个月之后，我的项目里已经积累了几十条规则。比如“Element Plus 的 el-table 列宽设置不要用百分比，一律用固定像素或自适应”、“vue3 项目里别用 Vue2 风格的$set，直接用赋值 + reactive 自动响应”、“pinia 的 store 不要在里面放可变的大对象，会拖垮响应式性能”。这些规则看着零碎，但 AI 拿到它们之后生成的代码质量，是真的肉眼可见地提升。

我提醒一下：把 AI 当“搜索引擎”用时，它给你的答案大概率是“最热门的写法”而不一定是“最适合你项目的写法”。Skills 存在的意义，就是把这些通用答案强行掰向你的项目实际。

3. 避坑指南：Vue3 项目里我踩过的那些高频坑

3.1 环境与工程化坑

Vue3 的环境配置看起来简单，实际踩坑的人不少。最大的坑永远是版本不匹配。我见过太多人把 Node 16 配 Vite 5，然后就出现各种奇怪的运行时错误。Vite 5 要求 Node 版本 18+，很多旧项目里跑着的 Node 16 根本带不动。我自己现在统一用 Node 20 LTS 配 pnpm，基本告别了这类环境问题。

再说一个特别典型的：pxtorem（postcss-pxtorem）对 ECharts 不生效。这个问题在 vue3 管理系统里非常高频，因为后台项目基本都要做自适应，ECharts 图表也得跟着缩放，结果你配置完 postcss-pxtorem，发现图表内部的字体和宽高纹丝不动。原因很简单，postcss-pxtorem 是在编译阶段把 px 转 rem，它只处理样式表里的内容。而 ECharts 的尺寸和字体，很多是写在 JavaScript 配置项里的内联样式，压根儿不经过 postcss 这条链路，自然转不了。

解决办法有两个路径。第一，通过rem动态计算函数，自己写个工具方法，把图表配置里的所有 px 值包一层，例如fontSize: rem(14)。第二，监听window.resize事件，动态调整图表容器的宽高，再调用chart.resize()，同时配合 Rem 适配方案重设字体大小。我自己更倾向于第二种，因为改动小、侵入性低，而且对 ECharts 的性能影响可控。给 ECharts 容器设一个固定高度，然后通过 resize 监听 +resize方法刷新，是后台项目里最实用的一招。

再说 uniapp 从 Vue2 转 Vue3 的时候，很多人以为只要把vue2依赖换掉就能跑。实际上这里面暗坑一堆。最大的坑是uni.$emit和uni.$on的跨页面通信，在 Vue3 里由于实例化机制变化，部分平台可能出现监听不到事件的情况，特别是 App 端。替代方案是用uni.$emit配合掉onLoad之后onShow里重新绑定，或者直接切换成 pinia 做全局状态缓存。另外就是 Vue2 里常用的this上下文逻辑，在 Vue3 组合式 API 里全面失效，this.$refs的时机也变了，必须用ref+onMounted代替。我当时迁移一个商城项目的时候，光是筛选出这些this调用就花了一个下午，后来一怒之下写了个正则扫描脚本，把所有this.开头的行全列出来，再逐个替换，效率才拉起来。

3.2 组件与样式细节坑

Vue3 的组件样式坑主要集中在 scoped 和深度选择器上。后台管理系统里改 Element Plus 的el-tabs标签样式，是我看到过问得最多的问题之一。有人直接写了.el-tabs__item { color: red }，结果发现不生效，或者一旦生效就影响到了全局其他页面的 Tabs。原因很简单，Element Plus 组件内部的 DOM 结构是在子组件里渲染的，scoped 样式默认只作用于当前组件的 DOM 节点，所以你要改它内部元素就必须要用:deep()。

正确写法是：

:deep(.el-tabs__item) { color: #333; font-size: 14px; } :deep(.el-tabs__item.is-active) { color: #409eff; font-weight: 600; }

这里有一个很容易忽略的细节：:deep()的选择器前面不要加多余的类名限制，否则层级一旦和 Element Plus 内部的 DOM 结构不匹配，照样不生效。我在实际项目里就遇到过.my-tabs :deep(.el-tabs__item)因为中间隔着el-tabs__header和el-tabs__nav-wrap两层结构，导致样式匹配不到的情况。所以能用:deep()之前，先用 F12 打开开发者工具，看清楚实际渲染出来的 DOM 层级再写选择器，这个习惯能救你很多次。

另外 Vue3 里写 JSX 也是一个容易踩坑的点。很多人觉得 Vue3 用了 JSX 就像 React 一样自由，结果写出一些奇奇怪怪的代码。实际上 Vue3 的 JSX 和 React 的 JSX 有本质区别，最大的坑就是 v-model 的写法。在 template 里你写v-model="value"就好，到 JSX 里你得写v-model={value}，如果需要不同参数还得写v-model:modelValue。在 JSX 里直接写v-model={value}在构建时确实能通过，但它不会自动展开成modelValue和onUpdate:modelValue，很容易出现“绑定了但不生效”的诡异 bug。所以我的建议是：能写 template 就写 template，除非是需要在渲染函数里做动态组件编排，否则别为了一时的“自由”给自己挖坑。

3.3 性能与原理坑

理解 Vue3 的 diff 算法对日常排错真的很有用，这个不夸张。很多人写v-for的时候不在乎 key，随便用个 index 顶上。在 Vue2 里这可能只是轻微的性能损耗，但在 Vue3 里由于引入了带有静态标记的快速 diff 算法，key 的重要性变得更高。Vue3 的 diff 过程会先比较新旧子节点数组的两端，做前前对比、后后对比、新前旧后对比、新后旧前对比，最后才处理中间无序部分。如果你用了 index 作为 key，在数组头部插入一条数据时，index 会整体后移，Vue3 不得不把后面所有节点都当作发生了移动或者变化来处理，性能直接拉胯。

实际项目中我还遇到过因为 key 使用不当导致的表单状态错乱。比如一个列表里有输入框，你往列表头部加了一项，由于 key 是 index，原本第一行的输入内容就“粘”到了第二行上，用户输入的东西对不上号。这种情况在 Vue2 里偶尔也会出现，但 Vue3 的 diff 机制让这种问题更容易被暴露出来。所以我建议给所有v-for的 key 都用业务主键，实在没有唯一 id 就用组合字段，比如index + '_' + item.code，但绝对不要裸用 index。

另一个性能大头是地图组件的集成。vue3 里接 mapboxgl，最大的坑是生命周期管理。地图实例创建之后，如果组件销毁时没有手动调用map.remove()，内存泄漏是必然的，特别是在后台管理系统里反复切换路由页面时，浏览器内存会肉眼可见地上涨。正确做法是在onBeforeUnmount里销毁地图实例，同时移除所有监听事件。还有一个细节是地图容器必须要有确定高度，否则初始化时拿到的是 0，地图只显示一片灰。我习惯在模板里给容器写死一个 min-height，然后在onMounted里初始化地图，用nextTick确保 DOM 渲染完成后再创建实例。

3.4 从 Vue2 迁移到 Vue3 的隐含成本

这里特别说一下 uniapp 或老项目从 Vue2 迁移到 Vue3 的问题，这确实是很多人正在经历的痛苦阶段。表面上看起来只是“换依赖 + 改语法”，但真正贵的地方在于心智模型的变化：选项式 API 的data/computed/methods/watch是分开的生命周期槽位，组合式 API 把相关的逻辑都揉进setup里。迁移时最常见的错误是机械地把data变成ref，把methods变成普通函数，但没有注意this的上下文依赖。

我的迁移顺序是：先跑起项目，处理编译错误，再逐个页面处理运行时报错，然后统一重构状态管理为 Pinia，最后才是做性能优化。盲目地从第一个文件开始改，很容易改了半个月发现项目还跑不起来，心态直接崩了。另外迁移时要善用 ESLint 规则，比如vue/no-deprecated-destroyed-lifecycle这类插件能帮你扫出不少废弃 API。还有一个很难注意到的地方：Vue3 中$listeners已经合并到$attrs里，如果你的项目之前大量用了v-on="$listeners"的自定义组件，迁移时这些都会失效，得手动逐个确认事件绑定。这种“隐性语法变更”最坑人，因为它不会给你编译错误，只是运行时不触发。

4. 问题排查与 AI 辅助实操记录

4.1 一套可复用的 AI 排查问题模板

用 AI 排查 Vue3 问题，最大痛点不是 AI 不会答，而是你问得太抽象。“我这个页面白屏了帮我看下是什么原因”，这种问法，神仙 AI 也救不了你。我后来自己总结了一套问题描述模板，塞在 Skills 里，每次出问题都按这个模板向 AI 提问，回答准确率直接翻倍。

模板如下：

项目基础信息：Vue 3.4.x + TypeScript + Vite 5 + Element Plus + Pinia 问题现象：页面在点击查询按钮后，表格数据没有刷新，控制台无报错 相关代码文件： - src/views/user/index.vue - src/api/user.ts 关键代码片段： <贴出对应代码> 已尝试的排查步骤： 1. 已在 onMounted 中调用过 fetchList，初次加载正常 2. 点击查询时手动调用 fetchList，断点显示接口正常返回 期望结果：点击查询后，表格数据按照筛选条件重新加载 实际结果：表格数据不变，但接口确实拿到新数据

这样一份描述丢给 AI，它能在 10 秒内锁定问题方向，比如“你可能用错了响应式对象，table 的数据源没有正确触发更新”。我在实际项目里用这个模板排查了好几次问题，准确率相当高，最典型的一次是排查出一个“pina store 里state的数组被直接push新值，但没有替换引用导致表格不更新”的老坑。

4.2 典型问题速查表

我在 Vue3 项目实战中踩坑最多、被同事问得最多的几个问题，整理成一个速查表，基本上覆盖了新手到中级开发会遇到的 90% 场景。

这张表我建议直接收藏，尤其是做后台管理系统的，每一个都亲测有效。AI 排查问题的时候，我会把这张表也丢到它的上下文里，作为一个“常见问题预筛器”，能帮它快速排除掉一批已知问题。

4.3 让 AI 少犯错的三个实战技巧

第一，给 AI 贴报错原文和文件片段，而不是用“帮我查一下为什么表格不刷新”这种模糊描述。很多新手怕代码贴多了 AI 看不懂，反而只给一句报错信息，结果 AI 只能凭猜测作答，错误率极高。我的做法是至少贴出“文件顶部 import 区 + 报错所在函数 + 控制台的完整报错”，三样缺一不可。AI 拿到了上下文，回答才靠谱。

第二，设置“先分析再给代码”的约束。很多 AI 默认会直接输出修改后的代码，但如果你不问它的分析逻辑，你根本不知道它改了什么，也无法判断改动会不会影响其他模块。所以我所有的 Vue3 专属 Skills 里都会写一条硬性规定：不能直接给代码，必须按“错误原因 → 影响范围 → 修改方案 → 完整代码”的顺序输出。这样我看一眼原因和影响范围，基本就能判断这个方案靠不靠谱，不用傻乎乎地跑完代码才发现方向错了。

第三，让 AI 给你的方案“挑刺”。这是我最近发现的一个很实用的技巧。当 AI 给出一版方案后，我会追加一句：“请列出这个方案的三个潜在问题，以及对应的兜底方案。”这样做听起来多此一举，但实际效果是真的好。因为 AI 在生成代码时天然倾向于“自信输出”，你逼它思考反例，它会从深层的类型问题、边界条件、性能隐患这些角度再扫一遍，很多隐藏的雷当场就给排了。

4.4 Skills 迭代的下一步规划

现在这套 Vue3 Skills 在我的项目里已经稳定跑了三个多月。下一步我打算把它的范围扩大到可视化大屏和低代码平台这两块。可视化大屏项目里，ECharts 的类型定义、主题切换、大数据量的按需更新都是可以沉淀成规则的。低代码平台就更复杂了，设计器拖拽布局与渲染器之间的事件联动，Vue3 组件的动态渲染，这些靠传统代码很难维护，反而更适合让 AI 配合 Skills 来做生成。

如果你平时也在用 AI 写 Vue3 代码，我的建议是从今天开始就建立一个自己的 Skills 库，不用多，一开始五到十条规则就好。把每次排查问题的结论、每次 AI 犯错的教训都存进去，等到了二十条的规模，你基本就能感受到“AI 越来越懂你的项目”是一种什么体验了。这套模式，会成为你在 Vue3 开发上提速的一个关键转折点。