Vue 官网使用与环境搭建这两件事，看起来像是新手入门第一天就要过的两道小坎，实际做下来，很多人写了半年 Vue 项目，官网还是只用来顺手复制一段示例代码。我见过太多人卡在依赖安装转圈、命令行报一堆看不懂的错，也见过有人直接照抄官网的选项式写法，结果在自己的组合式项目里越写越乱。这篇就按我自己的习惯，把官网当成一本随时能翻的工具书来用，再把从零到本地服务跑通、构建能出包、编辑器不飘红的每一步掰开揉碎讲明白。不管你是刚接触前端、准备做一个小型练手项目，还是已经会用框架但环境总是配不顺，下面的内容都可以直接照着做，中间那些“为什么这么选”的取舍我也会讲透，省得你后面返工。
1. 官网不是“看一眼就走”的地方：先建立自己的查阅路径
1.1 官网到底分成哪几个大块，各自解决什么问题
很多人打开官网，第一眼看到首页那句简短介绍和“快速上手”按钮，点进去复制一段命令就跑了，后面再也没系统看过。我的建议是先花二十分钟把导航栏摸一遍，知道哪块内容该去哪个入口找，这二十分钟后面能省你几十次搜索。官网的顶层导航基本是这么几块：指南（Guide）、API 参考、教程 / 演练场、生态系统、工具链。这几块的定位完全不同，混着用会很低效。
指南解决的是“这个概念是什么、我该怎么用”的问题，属于叙述性内容，适合从头读或者按主题跳读。API 参考则是“函数签名、参数含义、返回值”的速查表，你写代码写到一半忘了某个方法的第二个参数是什么，去那里最快。演练场是能直接在浏览器里改代码看效果的在线编辑器，学新概念的时候用它验证想法特别方便，不用在本地建工程。生态系统那一栏列的是官方维护的配套方案和推荐库，路由、状态管理、构建工具、服务端渲染框架都在里面。工具链那块讲的是编辑器支持、测试、类型检查这些开发体验相关的东西。
我自己的习惯是：遇到“为什么这样写”的困惑去指南，遇到“这个参数填什么”的困惑去 API 参考，遇到“这个东西能不能直接改着玩”就去演练场。把这三个入口在心里定好位，你打开官网的目的性会强很多，而不是每次都从首页开始漫游。
1.2 指南里的章节顺序是有意安排的，别乱跳
指南的目录不是随便排的。它大致按“快速上手 → 基础 → 组件深入 → 逻辑复用 → 内置组件 → 规模化 → 最佳实践 → 类型系统 → 进阶话题”这条线走。这条线背后是一套学习路径设计：先让你能跑起来看到效果，再讲响应式、模板语法这些每天都要用的基础，然后才深入组件的 props、事件、插槽、生命周期，接着讲组合式函数怎么复用逻辑，最后才谈大型项目怎么组织、怎么做类型约束。
新手最容易犯的错是直接跳到“规模化”或者“最佳实践”那几章，结果看到一堆目录结构和设计模式，完全不知道为什么要这么设计。我的建议是，哪怕你已经有其他框架经验，也至少把基础那一章快速过一遍，因为 Vue 的响应式模型和模板编译方式跟别的框架差异不小，很多“看起来应该这样写”的直觉在这里是错的。比如你在别的框架里习惯手动触发更新，在 Vue 里改完数据就自动更新了，再比如解构响应式对象会丢响应性这种坑，基础章节里都提过，跳过去就得在项目里踩一遍才明白。
组件深入那一章要重点看，尤其是 props 的单向数据流、自定义事件、插槽的几种形态（默认插槽、具名插槽、作用域插槽）。这几样东西是日常写业务组件的基础，官网给的示例都很短，但每个示例背后都有设计意图，比如为什么 props 不建议在子组件里直接改，为什么事件要用 emit 而不是回调函数传下去。看懂这些意图，你写出来的组件接口才不会别扭。
1.3 API 参考要配合指南看，而不是单独背
API 参考按组合式 API、选项式 API、全局 API、内置组件、单文件组件语法这几类分开列。我见过有人把 API 参考当字典从头翻，翻两页就放弃了，因为那里全是签名和参数表，没有上下文。正确用法是把它当查号台：写代码时想不起来某个函数怎么用，去查一下签名和示例，看完就回来继续写。
但有一类 API 值得你主动去翻一遍，就是组合式 API 里那几个“响应式工具”和“生命周期钩子”。响应式工具包括创建响应式对象的几个函数、把普通值包成响应式的函数、以及几个用来做类型判断和转换的工具函数。这几个函数的区别（尤其是深层响应式和浅层响应式、只读和可写）如果不搞清楚，很容易在性能或者数据流上出问题。生命周期钩子那一页会明确告诉你每个钩子触发时机，以及服务端渲染环境下哪些钩子不会执行，这个在做同构渲染时特别关键。
还有一个容易被忽略的入口是单文件组件语法那一节。里面讲了<script setup>这种写法的编译规则、顶层绑定怎么暴露给模板、defineProps和defineEmits这些编译宏的用法限制。这部分内容不长，但如果你用的是这种写法，它几乎是必读的，因为很多“为什么这里不能写 await”“为什么这个变量模板里访问不到”的问题，答案都藏在这一页。
1.4 生态系统那一栏是选型地图，不是广告位
生态系统那一栏列的东西分两类：一类是官方维护、和核心库同步演进的，比如路由方案、状态管理方案、构建工具、服务端渲染框架；另一类是社区维护但官方推荐的，比如工具库、组件库、测试工具。这一栏的价值在于，当你需要某个能力时，先来这里看看有没有官方认可的方案，再决定要不要去外面找。
举个我自己的例子：早期做项目时想找一个“组合式函数集合”，外面搜出来一堆质量参差的库，后来在生态系统里看到官方推荐的某个工具库，里面把常见的鼠标位置、本地存储、防抖节流、元素尺寸监听这些封装得很干净，直接省掉我自己写一堆重复逻辑。再比如状态管理，新手常纠结“到底要不要上状态管理库”，生态页里会明确告诉你它适合什么规模的项目、和组件内状态怎么分工，看完心里就有数了。
2. 环境搭建前的取舍：运行时版本、包管理器与源配置
2.1 Node 版本怎么定，别用“最新的”也别用“最老的”
前端工具链对 Node 版本是有硬性要求的。构建工具的新版本通常会声明最低支持的 Node 主版本，低于这个版本启动就会直接报错。我的建议很直接：用当前处于长期支持（LTS）状态的那个偶数版本，或者它前一个 LTS 版本。奇数版本是过渡版本，生命周期短，工具链适配也未必跟得上，日常开发没必要追。
具体怎么查？命令行敲node -v看当前版本，敲npm -v看包管理器版本。如果版本太老，去 Node 官网下载 LTS 安装包覆盖安装就行。但这里有个坑：不要在同一台机器上直接覆盖安装多个版本，因为有些老项目依赖旧版本 Node，新项目又要新版本，来回卸载重装非常痛苦。正确做法是装一个版本管理工具，常见的有 nvm、fnm、volta 这几种。
我用的是那种按项目目录自动切换版本的工具，在项目根目录放一个版本声明文件，进目录就自动切到对应版本，出目录切回默认。配置方式大致是这样：先在项目根目录创建版本文件，写上需要的版本号，然后在 shell 配置文件里加上自动切换的初始化脚本。这样你同时维护三个项目、每个项目 Node 版本不同，也不会互相打架。版本文件记得提交到代码仓库，团队其他人拉下来就能自动对齐。
注意：版本文件里的版本号要写具体主次版本，不要只写一个模糊的范围，否则不同机器解析出来的实际版本可能不一致，出现“我这里能跑你那里跑不了”的经典问题。
2.2 npm、pnpm、yarn 到底选哪个
这三个都是包管理器，功能上都能完成“读依赖清单、下载依赖、生成锁文件、执行脚本”这几件事。区别在安装策略和磁盘占用。npm 是随 Node 一起装的，开箱即用，生态兼容性最好。yarn 早期靠更快的安装速度和更确定的锁文件赢得一批用户，现在和 npm 的差距已经不大。pnpm 用的是硬链接加内容寻址的存储方式，多个项目共享同一份依赖文件，磁盘占用小、安装速度快，对依赖的“幽灵引用”问题管得也更严。
我的实际取舍是：个人项目和小团队项目优先 pnpm，公司里如果有统一规范就跟着规范走。pnpm 的严格性一开始会让你不习惯，因为它不允许你引用没有在依赖清单里声明的包，而 npm 的扁平化安装经常让你“碰巧”能引用到别人的依赖。这种严格其实是好事，能提前暴露依赖声明不全的问题，避免上线时才炸。但如果你的项目依赖了某些老库，它们内部对依赖提升有假设，pnpm 可能会报模块找不到，这时候要么加配置做依赖提升，要么老老实实退回 npm。
安装 pnpm 的方式很简单，用 npm 全局装一次就行。装完可以用pnpm -v验证。需要注意的是，同一个项目不要混用多个包管理器的锁文件，如果仓库里同时存在几种锁文件，说明历史上有不同的人用不同工具装过，这时候应该删掉多余的，统一用一种，否则 CI 上装出来的依赖树可能和本地不一致。
2.3 registry 地址与镜像源的配置思路
默认的包仓库地址在部分地区访问会比较慢，安装大依赖时容易超时。常规做法是把 registry 指向一个访问更顺畅的镜像地址。配置命令很简单，在命令行里设置全局 registry 即可，设完可以用查询命令确认当前生效的地址。
但这里有几个实操细节值得说。第一，镜像源的同步是有延迟的，刚发布的新版本包可能在镜像上还没有，这时候临时切回官方源安装单个包，装完再切回来，比干等更快。第二，不要把 registry 配置写死在项目文件里提交到仓库，因为团队里不同人的网络环境不同，写死会让别人装不上。配置放在用户级的全局配置文件里最合适，每个人自己维护。第三，如果你所在的环境需要通过一个中间地址访问外网，这个地址的配置方式因工具而异，npm 用配置项，pnpm 和 yarn 有各自的写法，配错了会出现“命令行能访问但安装就是失败”的怪现象。
还有一个容易被忽略的点是锁文件里记录的下载地址。如果你之前用官方源装过依赖，锁文件里会记下官方源的地址，之后即使你切了镜像源，安装时仍可能按锁文件里的地址去拉，速度还是慢。解决办法是删掉锁文件和依赖目录重新装一次，让它按新配置生成。这个操作在换机器或者换网络环境后建议做一遍。
3. 用官方脚手架跑起第一个项目：命令、选项与目录结构
3.1 为什么现在新建项目不推荐老脚手架了
早几年新建 Vue 项目，大家用的是那个基于 webpack 的命令行工具，交互式地问你一堆问题，然后生成一套配置。现在官方推荐的方式换成了基于新一代构建工具的脚手架。原因不复杂：新构建工具在开发阶段的启动速度和热更新速度明显更快，配置也更简洁，配置文件短到几十行就能覆盖大部分需求。
老脚手架不是不能用了，它维护模式还在跑，存量项目也大量在用，但你新起一个项目没必要再选它。新脚手架的开发服务器启动通常是秒级，改一行代码保存，浏览器里的变化几乎是即时的；构建产物也做了更好的代码分割和资源处理。我实测过一个中等规模的项目，从冷启动到页面可交互，新旧两套工具差距能到好几秒，日常开发频繁重启的时候这个差距很影响心情。
新脚手架的创建命令是一条交互式命令，跑起来之后它会问你一系列问题，包括项目名、要不要加 TypeScript、要不要加 JSX 支持、要不要路由、要不要状态管理、要不要测试、要不要代码规范和格式化工具。这些选项全都可以后续手动补，选错了也不用重来，但一开始选对能省不少配置工作。
3.2 交互选项逐条解读，选之前先想清楚
项目名：命令行参数里可以直接给，也可以在交互里填。名字里不要带大写字母和空格，用短横线连接单词，这是包名的通用约定，带了特殊字符后面在某些工具里会出问题。
TypeScript：如果你之前没写过 TS，我建议新项目直接选上。不是说非得用类型标注，而是现在的编辑器对 TS 的支持太好了，很多错误在你敲代码的时候就能提示出来，比运行时才发现强太多。而且选了 TS 之后，脚手架会生成配置文件，你哪怕暂时只写很少的类型，也能享受编辑器的自动补全。反过来，如果你所在团队完全没有 TS 基础，强行上会拖慢进度，那就先不选，后面想加也来得及。
JSX 支持：只有你确定要在项目里用 JSX 写渲染函数才需要选。绝大多数业务项目用模板语法就够了，选了会增加一点编译配置，但不影响运行。
路由：做多页面应用基本都要选。选了之后脚手架会生成路由配置文件和两个示例页面，还会把入口改成挂载路由的方式。如果你只是做一个单页的小工具，不选也行，省得后面删示例代码。
状态管理：这个要看你项目规模。几个页面之间共享一点用户信息，用组件传参或者简单的响应式模块就够了，没必要上状态库。但如果项目里有跨多层的共享状态、需要持久化、需要调试工具追踪状态变化，那就选上。我的经验是，中等以上规模的项目选了不亏，小项目选了会多一层理解成本。
测试：单元测试和端到端测试分开问。单元测试适合工具函数和组件逻辑的验证，端到端测试适合跑完整用户流程。新项目如果时间紧，可以先不选，等核心功能稳定了再补。但如果这个项目要长期维护，一开始就选上单元测试，能逼着你把逻辑写得更可测，长期收益很大。
代码规范与格式化：这两个我建议都选。规范工具负责发现潜在问题（比如用了未定义的变量、写了永远为假的条件），格式化工具负责统一代码风格（缩进、引号、分号、换行）。两个配合使用，提交前自动跑一遍，团队里就不会出现一个人用两个空格一个人用四个空格的混战。要注意的是，这两个工具的规则偶尔会打架，需要装一个桥接插件让格式化工具按规范的规则来格式化，具体配置脚手架一般会帮你处理好。
创建完成后，进入项目目录，安装依赖，然后跑开发命令。第一次安装会花一点时间，之后有缓存就快了。
3.3 目录结构逐个拆解，知道每个文件夹该放什么
脚手架生成的目录结构大致是这样的：根目录下有入口 HTML 文件、构建配置文件、TypeScript 配置、包清单和锁文件，以及源码目录和静态资源目录。我按重要性逐个说。
入口 HTML 文件放在根目录，构建工具会把它当成页面模板，里面的挂载点是一个 id 固定的空 div。你可以在里面加一些全局的 meta 标签、字体引用，但不要把业务代码写进去。这个文件在构建时会被处理，资源引用路径会被自动改写。
源码目录是整个项目的核心，进去之后通常有这些子目录：assets放需要被构建工具处理的静态资源，比如图片、样式文件、字体，这里的资源在引用时会被加上哈希、做压缩优化；components放可复用的组件，我一般按业务模块再分子目录，公共组件单独放一个目录；views或pages放路由级别的页面组件，每个页面对应一个文件；router放路由配置，定义路径和组件的映射关系、导航守卫；stores放状态管理的模块定义，每个模块一个文件；composables放组合式函数，也就是把可复用的逻辑抽出来的那些函数，这是组合式 API 时代最重要的复用手段。
根目录那个public文件夹和 assets 不一样，里面的文件会被原样复制到构建产物里，不做处理，适合放 favicon、robots.txt 这种不需要构建处理的文件。引用 public 里的资源要用绝对路径，不能用相对路径，因为构建后路径关系会变。
构建配置文件是改构建行为的地方，比如配路径别名、配开发服务器端口、配反向转发规则、配构建输出目录。这个文件不长，但每次改都要重启开发服务器才生效。
TypeScript 配置文件通常不止一个，一个管编辑器里的类型检查，一个管实际构建时的编译。新手容易只改一个然后发现另一个不生效，改之前先看清楚注释说明。
包清单文件里除了依赖版本，还有脚本命令的定义。脚本是很实用的东西，你可以把常用的长命令封装成短命令，比如把“跑测试 + 跑规范检查 + 构建”串成一条发布前检查命令，提交前跑一遍，能挡住大部分低级错误。
3.4 四条核心命令，以及它们背后发生了什么
脚手架会在包清单里预置几条脚本，最常用的四条是：开发、构建、预览、检查。
开发命令启动的是开发服务器，它会做几件事：预构建依赖（把第三方库提前打包成浏览器能直接加载的格式，避免每次刷新都现场编译）、启动本地服务、监听文件变化并做热更新。热更新的意思是，你改了一个组件的样式，页面不会整页刷新，只替换那部分，当前页面的滚动位置和表单输入都会保留。这个体验对调试表单类页面特别重要。
构建命令做的是生产打包：把源码按路由和组件拆成多个块、压缩代码、提取样式、给资源加内容哈希（这样改内容后文件名会变，浏览器缓存能正确失效）、做 tree-shaking 去掉没用的代码。构建产物默认输出到一个固定目录，这个目录不该提交到仓库，应该在忽略文件里排除掉。
预览命令会在本地起一个服务，把构建产物按生产方式跑起来。这个命令很有用，因为开发服务器和真实构建产物之间可能有差异，比如某些环境变量的读取方式、某些资源路径的处理。上线前用预览命令把主要流程点一遍，能提前发现一类只在构建后出现的问题。
检查命令跑的是代码规范检查和格式化。我习惯把它配到提交钩子里，提交前自动跑，不通过就拦住。一开始会觉得烦，用两周之后就离不开了，因为团队里再也不会出现格式混乱的提交。
4. 编辑器与工具链：让代码写起来不别扭
4.1 插件组合怎么搭，装多了反而互相打架
编辑器这块，主流选择里对 Vue 支持最好的还是那套组合。核心是一个官方维护的语言支持插件，它负责解析单文件组件、提供模板里的补全和类型检查、支持跳转定义。这个插件早期叫另一个名字，现在统一了，装的时候认准官方发布的那一个。
除了核心插件，还需要一个 TypeScript 相关的辅助插件，它让编辑器能把单文件组件里的类型信息正确传递给 TS 服务，没有它的话，你在模板里引用组件、访问 props 时补全可能不全。
然后是规范检查和格式化两个插件，把命令行的检查结果直接标在编辑器的波浪线上，鼠标悬停就能看到问题描述，配合保存时自动格式化，基本不用手动整理代码。
这里有个大坑要特别注意：不要同时装新旧两套 Vue 语言支持插件。老的那套插件和新的一套会抢同一个语言服务的注册权，表现是补全时有时无、模板里一片红色报错、跳转跳到奇怪的位置。如果你是从老项目迁移过来的，先去插件列表里把老的禁用掉，再重启编辑器。
还有一个常见问题是工作区级别的配置覆盖了用户级配置，导致“我明明装了插件为什么没生效”。检查方式是打开工作区设置文件看一眼，有没有把格式化工具的默认选项关掉。
4.2 路径别名与类型提示，让导入语句短一点
项目稍微大一点，就会出现这样的导入语句：从三层目录外面导入一个组件，路径写成一段长长的相对路径，重构挪动文件时全得改。解决办法是配路径别名，把源码目录映射成一个短前缀，导入时直接用前缀加子路径。
配置分两处：构建工具里配一份，告诉打包器怎么解析；TypeScript 配置里配一份，告诉编辑器怎么解析。两处都配了，编辑器里才有正确的跳转和补全。只配一处的话，要么构建报错，要么编辑器飘红。
配完之后，导入语句会短很多，可读性明显提升。但要注意别滥用别名，同一模块内部的相对导入还是用相对路径更直观，别名主要用在跨模块引用上。
4.3 路由、状态库和组件库的按需引入
路由和状态库如果在创建项目时选了，脚手架已经配好基础结构，你需要做的是往里加具体内容。路由那边要定义路径、组件映射、懒加载（用动态导入让每个页面单独打包，首屏不用加载全部代码）、导航守卫（做登录校验、标题设置这类事情）。状态库那边要定义模块、状态、修改方法，然后在组件里按需引入使用。
组件库的引入方式取决于库本身的设计。有些库支持按需引入，你只用到几个组件，构建时只会打包这几个；有些库需要全量引入，体积会大一些。判断方式是看库的文档里有没有“按需引入”或者“自动导入”的章节。我一般优先选支持按需引入的方案，尤其是移动端项目，首屏体积直接影响体验。
自动导入插件是个好东西，它会在编译时扫描你用了哪些组件和函数，自动帮你补上导入语句，代码里就不用写一堆 import。但自动导入也有代价：代码的可读性会下降，新人看代码时不知道某个函数从哪来的；另外某些情况下插件的扫描会漏，需要手动补。我的折中做法是，组件和常用工具函数用自动导入，业务逻辑和状态管理显式导入，兼顾效率和可读性。
5. 常见问题排查实录：从安装到启动的典型故障
5.1 安装阶段：卡住、超时、权限被拒
安装卡住是最常见的。表现是命令行停在那里不动，或者反复重试最终超时。排查顺序是这样：先看网络能不能正常访问 registry 地址，用一条简单的查询命令测试；再看是不是锁文件里记的地址和你现在配的不一致，不一致就删掉锁文件和依赖目录重装；最后看是不是全局配置里混进了无效的源地址，用配置查询命令把所有相关配置打出来核对。
权限被拒通常出现在全局安装或者用了系统级目录的情况。报错里会带权限相关的字样。解决办法有两个方向：一是把全局安装目录改到用户目录下，避免写系统目录；二是用版本管理工具装 Node，这类工具会自己管理目录权限，装出来的环境天然没有这个问题。我不建议直接加提权命令跑安装，那样装出来的文件属主是管理员，后续普通用户跑脚本时会出现新的权限问题，越弄越乱。
还有一种偶发情况是磁盘空间不足或者依赖目录文件数过多导致的文件系统报错。表现是安装到某个包时突然失败，报文件写入错误。清理一下依赖目录和包管理器缓存再装，通常能解决。
5.2 启动阶段：端口占用、模块找不到、页面白屏
开发服务器起不来，最常见的是端口被占。报错里会明确写端口已被使用。解决办法要么杀掉占用端口的进程，要么在配置里改一个端口，要么让开发服务器支持“端口被占就自动往后找”的选项。我一般直接配自动找端口，省得每次手动改。
模块找不到的报错要看完整信息。如果报的是某个依赖包找不到，可能是依赖没装全，删了重装；可能是包管理器严格模式不允许引用未声明的依赖，需要把它加到清单里；也可能是依赖目录的缓存坏了，删掉缓存目录重启。构建工具一般会把缓存放在依赖目录下的一个隐藏文件夹里，删掉它不会影响源码，下次启动会重新生成。
页面白屏但控制台没有明显报错，这类问题最烦。排查步骤是：先看浏览器控制台的网络面板，看主要资源有没有加载成功，特别是入口 JS 文件和样式文件；再看控制台有没有脚本执行错误，有时候错误被异步逻辑吞掉了，需要加断点或者临时加日志；最后看挂载点 id 和入口文件里创建的根实例挂载目标是否一致，名字对不上就会挂载失败，而且往往不报错，就是白屏。
热更新不生效是另一个高频问题。表现是改了代码，浏览器没反应，手动刷新才有变化。常见原因是文件路径大小写不一致（某些系统对大小写不敏感，构建工具按配置里的路径去找，找不到监听目标）、编辑器用了“安全写入”模式（先写临时文件再重命名，监听器跟不上）、或者监听数量超出了系统限制（大型项目文件多的时候会遇到，需要调高系统级别的监听上限）。
5.3 类型报错与编辑器飘红
编辑器里一片红但命令行构建能过，说明编辑器的类型服务和构建时的类型检查用了不同的配置。排查方式是打开 TS 配置文件，看编辑器读取的是哪一个，通常有个文件专门给编辑器用，有个专门的引用文件把多个配置串起来。两边的路径别名、包含范围要保持一致。
模板里的类型报错还有一种情况是组件的 props 定义方式和类型推断不匹配。比如用运行时声明的方式定义 props，编辑器就从运行时信息里推断类型；用类型标注的方式定义，推断会更准确。混用两种方式容易让编辑器犯迷糊，建议一个项目里统一用同一种。
5.4 常见问题速查表
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 安装命令长时间无响应 | registry 地址不可达或锁文件指向旧地址 | 检查当前 registry，删锁文件和依赖目录重装 |
| 安装报权限错误 | 全局目录位于系统路径 | 改全局目录到用户目录，或用版本管理工具 |
| 开发服务器启动失败 | 端口被占用 | 杀进程、换端口或开启自动找端口 |
| 报某个包找不到 | 依赖未声明或被严格模式拦截 | 补进依赖清单，检查依赖目录完整性 |
| 页面白屏无报错 | 挂载点 id 不匹配 | 核对入口 HTML 与根实例挂载目标 |
| 改代码页面不更新 | 文件监听失效或路径大小写不一致 | 检查文件名大小写，调高监听上限，关掉编辑器安全写入 |
| 编辑器飘红但构建通过 | 编辑器与构建的类型配置不一致 | 对齐两边的路径别名和包含范围 |
| 构建产物体积异常大 | 组件库全量引入或未做代码分割 | 改按需引入，路由用动态导入 |
| 样式在开发时正常构建后丢失 | 样式作用域或引入方式问题 | 检查样式是否只被动态导入的组件引用 |
6. 我自己反复用到的几个小习惯
写项目这么久，有几个习惯是每次新建项目都会做的，花不了几分钟，后面能省很多麻烦。第一个是把版本文件放在项目根目录并提交，团队里谁拉代码都自动对齐运行时版本，避免“我这里好的”这种对话。第二个是把常用脚本封装好，尤其是发布前检查那一条，把规范检查、类型检查、单元测试、构建串起来，跑通再提交，低级错误在本地就挡住了。
第三个是建一个自己的官网书签分组，把指南、API 参考、演练场、生态系统、工具链这几页都存进去，遇到问题先在这几页里找，找不到再去外面的社区。这个习惯养成之后，你会发现大部分“奇怪”的问题其实官网都写过，只是当时没读到。
第四个是新建项目之后先把示例代码删干净再写自己的。脚手架生成的示例页面和示例组件留着容易让人误以为那是项目结构的一部分，实际动手时又在旁边另起一套，最后两套风格混在一起。我的做法是保留目录结构和配置，把示例内容清空，只留一个最简单的首页，然后按自己的业务往上搭。
最后说一个我踩过的坑。早期用包管理器的时候，我习惯在项目里混着用两种工具，觉得反正都能装。结果有一次上线构建失败，排查了半天发现是两种工具的锁文件同时存在，CI 上按其中一种装出来的依赖树和本地不一致，某个包的次版本差了半级，接口对不上。从那以后我严格一个项目只用一种包管理器，并且把多余的锁文件写进忽略规则里，再也没出过这类问题。
