013. 前端项目初始化与工程规范

学习目标

这一节开始搭建前端项目，并补齐工程化习惯。

学完后，你应该能理解：

为什么前端项目也要先建立规范；
Create React App 项目初始化的基本流程；
Yarn 和 lock 文件为什么要统一；
EditorConfig、Prettier、ESLint 分别负责什么；
CRA 环境变量为什么必须以 REACT_APP_ 开头；
.env、.env.production、.env.example 的区别；
为什么要写一个集中读取环境变量的 env.ts。

项目初始化

前端项目使用 React 和 TypeScript。

初始化后先做几件基础工作：

创建项目；
初始化 Git；
推送到远程仓库；
安装依赖；
删除默认示例文件；
准备环境变量；
建立工具函数目录。

这一步和普通 React 项目相似，但后续项目会接入后端、静态资源服务、上传服务、模型服务，所以一开始就要把配置边界整理清楚。

统一包管理工具

项目使用 Yarn 时，就不要再混用 npm。

如果同时出现 package-lock.json 和 yarn.lock，团队里不同人安装出来的依赖版本可能不一致。

建议：

使用 Yarn 就保留 yarn.lock；
删除 npm 的 lock 文件；
团队成员使用同一种安装命令；
lock 文件要提交到 Git。

lock 文件不是临时文件。它用来锁定依赖版本，让你、同事、服务器安装到尽量一致的依赖树。

EditorConfig、Prettier、ESLint

这三个工具负责的事情不同。

工具	作用
EditorConfig	统一缩进、换行、字符集等编辑器基础格式
Prettier	自动格式化代码风格
ESLint	检查代码质量和潜在问题

对只写过 JS 的开发者来说，可以这样理解：

EditorConfig 管“编辑器怎么保存文件”；
Prettier 管“代码排版长什么样”；
ESLint 管“代码里哪些写法可能有问题”。

它们不是互相替代，而是互相配合。

在 IDE 里配置格式化

安装 Prettier 后，还要确认编辑器真的使用它。

常见配置包括：

保存时格式化；
指定 Prettier 包路径；
指定格式化规则文件；
确认 TypeScript、TSX 文件都能被格式化。

如果团队没有统一配置，每个人保存出来的代码都会不一样，后面 Git diff 会很乱。

环境变量文件

前端项目需要区分不同环境。

常见文件：

文件	作用
`.env`	本地开发使用
`.env.production`	生产环境构建使用
`.env.example`	给团队看的配置模板

.env 里可以放本地真实地址，但 .env.example 只放字段名和示例值，方便别人知道需要配置什么。

CRA 环境变量前缀

Create React App 读取前端环境变量时，变量名必须以 REACT_APP_ 开头。

例如：

env

REACT_APP_API_BASE_URL=http://localhost:8000
REACT_APP_STATIC_URL=http://localhost:8000/static
REACT_APP_UPLOAD_URL=http://localhost:8000/upload
REACT_APP_USE_MOCK=false

如果没有这个前缀，前端代码里通常读不到。

这是 CRA 的约定，不是所有前端工具都一样。Vite 项目会使用另一套前缀规则。

`.env` 注释要单独写一行

环境变量里不要随便把注释写在值后面。

集中读取环境变量

项目会创建 env.ts 之类的文件，把环境变量统一读出来。

这样做的好处是：

业务代码不用到处写 process.env；
变量名改动时只改一处；
可以统一做默认值；
可以统一处理布尔值和字符串转换；
后续排查配置问题更方便。

对 JS 开发者来说，这和封装一个 config.ts 很像。不要让配置散落在各个组件里。

前端工具函数准备

项目早期会先准备一些基础工具，例如：

类型声明；
错误提示；
环境变量读取；
后续模型、音频、请求相关工具。

这些工具看起来小，但它们会被后面的业务页面反复使用。

先把基础目录和规范搭好，后续写通用表格、AI 表单和请求封装时会顺很多。

013. 前端项目初始化与工程规范 ​

学习目标 ​

项目初始化 ​

统一包管理工具 ​

EditorConfig、Prettier、ESLint ​

在 IDE 里配置格式化 ​

环境变量文件 ​

CRA 环境变量前缀 ​

.env 注释要单独写一行 ​

集中读取环境变量 ​

前端工具函数准备 ​