Vue 3 项目的新人 onboarding 如果只给一份文档和仓库地址，很多人会在前两周反复卡在环境变量、路径别名、组件拆解和状态流这些非语法问题上。工程化培训体系的目标不是让新人背熟 API，而是把项目运行依赖的约定、脚本和协作流程变成一条可以照着走的学习路径。下面这张图可以先帮团队定位培训范围，通常包含脚手架、规范、分层、状态、测试与分享六个模块。
一、先建立 Vue 3 工程化知识地图
工程化培训的第一件事是让新人理解仓库为什么这样组织。以 Vite 驱动的 Vue 3 项目为例，核心入口不是 main.js 而是 vite.config.ts、package.json 和 src 下的目录约定。通常建议按领域划分目录，而不是按文件类型堆叠。例如 components、composables、stores、router、views、api、utils 各自独立，新人看到目录名就能判断代码归属。
我们可以给出一份最小的 Vite 配置示例。路径别名和代理设置是最常见的卡点，新人需要知道在配置中修改后，TypeScript 的 tsconfig.json 也要同步 paths，否则编辑器可以提示，但运行时解析可能失败。
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'node:path'
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
'@components': path.resolve(__dirname, 'src/components')
}
},
server: {
host: true,
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true
}
}
}
})
上面的配置会让 import 路径从 ../../components/HelloWorld 简化为 @components/HelloWorld。培训时应当要求新人自己走一遍修改别名的过程，而不是直接写死在模板里。环境变量文件 .env.development 和 .env.production 也需要单独讲解，变量名只有以 VITE_ 开头才会暴露给客户端代码。
规范工具链是知识地图的第二层。ESLint、Prettier、Husky 和 lint-staged 的组合可以在提交前统一格式。新人最容易忽略的是 git hooks 在 clone 之后不会自动生效，需要执行 npm run prepare 或 husky install。把这条写进 onboarding 文档能减少大量格式化冲突。
二、设计分阶段 onboarding 任务
一次性分配完整需求会让新人被业务和工程问题同时淹没。更稳的方式是把 onboarding 拆成三个阶段：环境验证、小型功能、跨模块状态流。每个阶段都有明确的提交要求和验收标准，而不是以时长作为完成标志。
第一阶段要求新人启动项目、修改一个简单组件、跑通 lint 和测试，并提交一个规范的 commit。提交信息需要符合 commitlint 配置，例如 feat: add greeting banner。这个阶段可以包含一条命令脚本，把检查过程固化下来。
{
"scripts": {
"dev": "vite",
"build": "vue-tsc --noEmit && vite build",
"lint": "eslint src --ext .ts,.vue",
"format": "prettier --write src",
"test": "vitest run",
"prepare": "husky install"
}
}
第二阶段让新人完成一个列表模块，包括接口请求、loading 状态、错误展示和空态。这个任务会自然覆盖组件通信、composables 封装和异步边界。培训文档应给出明确的组件拆分建议：列表容器负责数据获取，展示组件只接收 props 渲染，不要在展示组件里直接调用 API。
第三阶段引入 Pinia 状态管理。可以在任务中要求新人把用户信息或筛选条件放进 store，并且说明为什么这类状态不能只放在组件里。很多新人会过度使用 Pinia，把局部 UI 状态也放进全局 store，结果反而增加维护成本。培训时可以规定一条判断标准：只有跨页面或跨多层组件的状态才进入 store，其余优先用组合式 API 的 ref 和 reactive。
每个阶段建议配套一个检查表，包含功能完成、无 lint 错误、无 TypeScript 报错、关键路径有单测、提交信息符合规范等条目。检查表比口头说明更可靠，也方便 mentor 做 Code Review 时对照。
三、把技术分享嵌入培训节奏
技术分享不是 onboarding 结束后才开始的补充活动，而是帮助新人反向整理知识的手段。可以要求新人在第二周结束前做一次 15 分钟的内部分享，内容不是复述文档，而是围绕自己踩过的一个工程化问题展开。比如路径别名失效、环境变量不生效、watch 监听 props 不触发，都是很好的选题。
分享模板应当固定，避免变成零散的经验描述。模板可以包含问题现象、定位过程、根因、解决方式和沉淀出的预防规则。新人按照这个结构表达，既能检验自己是否真的理解，也能让其他成员复用结论。
# 分享主题：环境变量在构建后未更新 ## 问题现象 本地 dev 正常，build 后接口地址仍指向开发环境。 ## 定位过程 1. 查看 .env.production 是否被加载 2. 打印 import.meta.env.VITE_API_BASE 3. 检查构建缓存和 CI 环境 ## 根因 CI 脚本覆盖了 VITE_API_BASE，且变量名写成了 API_BASE，未带 VITE_ 前缀。 ## 解决方式 统一使用 VITE_ 前缀，在 CI 中显式注入变量。 ## 预防规则 新增环境变量必须通过 env.d.ts 声明类型，并在 onboarding 文档登记。
分享之后的讨论同样重要。mentor 可以在分享会上追问为什么这样排查、是否还有其他触发条件，帮助新人从单个问题上升到通用方法。团队还可以把分享内容沉淀到内部知识库，标注与 Vue 3 工程化相关的标签，方便后续检索。
四、常见卡点排查与考核清单
为了让培训体系可复用，建议把新人高频卡点整理成排查表。组合式 API 中的响应式丢失是最典型的问题之一。例如在 setup 中解构 props 会丢失响应式，正确做法是使用 toRefs 或直接通过 props.xxx 读取。
另一个高频问题是 ref 在模板中自动解包，但在 script 中访问必须使用 .value。新人往往会在 watch 第一个参数里直接写 ref.value，导致监听的是初始值而不是响应式引用。下面这段代码展示了两种常见错误和修正方式。
import { ref, watch, toRefs } from 'vue'
const count = ref(0)
// 错误：watch 的对象是具体数值，后续变化不会触发
watch(count.value, (val) => {
console.log(val)
})
// 正确：监听响应式源
watch(count, (val) => {
console.log(val)
})
const props = defineProps<{ title: string; visible: boolean }>()
// 错误：直接解构会破坏响应式
const { title, visible } = props
// 正确：使用 toRefs 保留响应式连接
const { title: titleRef, visible: visibleRef } = toRefs(props)
状态管理的考核点可以围绕 store 的模块边界设计。例如用户 store 只放用户信息、token 和权限码，订单 store 只放订单列表与筛选条件。让新人说明如果商品列表需要读取用户登录态，是直接调用用户 store 还是通过页面容器连接，能判断其对单向数据流的理解程度。
工程化培训最后的考核清单建议包含八项：能独立启动构建、能解释目录职责、能正确使用别名和变量、能处理异步请求与错误态、能说出 ref 和 reactive 的适用场景、能写出基础单测、能通过 lint 与 commit 校验、能完成一次 15 分钟技术分享。考核不是考试，而是让新人确认自己已经脱离纯模仿阶段，开始按工程约定做决策。
当这些模块串联起来后，新人 onboarding 就不再是导师的单向输出，而是一套有任务、有反馈、有沉淀的工程化流程。团队可以根据不同项目裁剪知识地图和分享节奏，但核心原则保持一致：用真实代码训练，用明确标准验收，用分享机制内化。
Vue 3工程化新人onboarding技术分享修改时间：2026-08-28 14:41:38