搭建一个最小前端工程

搭建一个最小前端工程

这篇笔记还在编辑中，内容可能会继续补充、调整或重写。

本阶段目标

创建贯穿本系列的 frontend-lab：一个包含列表、详情和编辑表单的 Vue 3 + TypeScript 应用。本阶段只建立最小运行闭环，不急着加入路由、状态库或复杂组件。

初始化项目

pnpm create vite frontend-lab --template vue-ts
cd frontend-lab
pnpm install --frozen-lockfile
pnpm dev

首次安装还没有 lockfile 时先执行 pnpm install，提交 pnpm-lock.yaml 后再使用冻结安装。团队应同时在 package.json 声明 packageManager，并通过 .nvmrc、.node-version 或 CI 配置固定 Node.js 主版本。

保留最小结构

frontend-lab/
├── src/
│   ├── App.vue
│   ├── main.ts
│   └── style.css
├── index.html
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
└── vite.config.ts

逐个回答这些问题：

  • index.html 为什么是入口的一部分，而不是构建后的普通静态文件？
  • main.ts 如何找到并挂载根组件？
  • 浏览器为什么能加载源码中的 .vue 和 .ts 文件？
  • dev、build 和 preview 三个命令分别验证什么？

故障演练

  1. 删除一个依赖后运行开发服务，观察模块解析错误包含哪些路径信息。
  2. 修改 Node.js 版本约束，让当前环境不满足要求，观察包管理器是否告警。
  3. 删除 lockfile 后重新安装并比较依赖图，理解为什么应用项目应提交 lockfile。

演练后恢复项目，并把现象、原因和修复记录到 docs/engineering-log.md。

验收标准

  • 新目录中执行 pnpm install --frozen-lockfile && pnpm build 能成功
  • README 写明 Node.js、pnpm 版本和启动命令
  • 能解释入口、开发服务器、插件、TypeScript 配置和生产产物的职责
  • 仓库不包含 node_modules、本地密钥或编辑器临时文件
  • 至少保留一次依赖解析失败的排查记录

下一篇：从零配置开发与生产构建。