很多前端项目刚拉下来时，最容易让新人困惑的往往不是业务代码，而是根目录里那一堆“看起来很像系统文件”的配置：.env、.editorconfig、.eslintrc.js、.prettierrc.js、craco.config.js、package.json、Dockerfile……
这些文件不是摆设。它们决定了项目怎么启动、代码怎么写、样式怎么约束、依赖怎么锁定、环境怎么区分，以及最后怎么部署上线。
下面这组图会按前端工程化的落地顺序，把常见配置文件串起来讲清楚：先搭好环境和编辑器体验，再接入代码规范、样式规范、构建定制、依赖管理、协作文档，最后把部署和自定义脚本补齐。
1. 先理解配置文件的分类
一个 React / CRACO 项目里，常见配置大致可以分成这几类：
- 环境与基础：
.env、.editorconfig、jsconfig.json - 代码规范：
.eslintrc.js、.eslintignore - 代码格式化：
.prettierrc.js、.prettierignore - 样式规范：
.stylelintrc.js、.stylelintignore - 构建与主题：
craco.config.js、craco-less.js - 依赖与包管理：
package.json、yarn.lock、.npmrc - 版本控制与文档：
.gitignore、README.md、QA.md、AGENTS.md、CLAUDE.md - 部署与容器化：
Dockerfile、Makefile、部署脚本、部署文档 - 自定义脚本：
extract-chine.js、myconfig.js、no-ds.js等
这些配置不是孤立的。比如 jsconfig.json 里的路径别名，最好和 craco.config.js 的 webpack alias 保持一致；.env 中的环境变量，也常常会影响构建、接口地址和部署脚本；ESLint、Prettier、Stylelint 又共同决定了团队代码质量和协作体验。
2. 环境与基础配置：先让项目“跑得对、写得顺”
.env：管理不同环境的变量
.env 用来放环境变量，例如接口地址、环境标识、功能开关等。对于 Create React App 来说，只有以 REACT_APP_ 开头的变量才会注入到前端代码里。
常见文件包括：
.env.env.development.env.production.env.local
注意：密钥、密码、私有 token 不要提交到仓库。前端环境变量最终可能进入构建产物，不能当成真正的安全边界。
.editorconfig：统一编辑器行为
.editorconfig 用来约定缩进、换行符、字符集、行尾空格等基础风格。它的价值在于让 VS Code、WebStorm 等编辑器在团队内尽量保持一致，减少“我的编辑器和你的不一样”带来的无意义 diff。
jsconfig.json：让编辑器理解项目结构
jsconfig.json 常用于配置路径别名和智能提示。例如把 src 作为基础目录，让你可以写：
import Button from '@/components/Button';
但要记住：jsconfig.json 主要服务编辑器体验，不等于 webpack 已经认识这个别名。构建层也要在 CRACO 或 webpack 中配置对应 alias。
3. ESLint：提前发现代码问题
ESLint 是静态代码分析工具，主要解决代码质量问题，而不是单纯解决格式问题。
它能帮助我们：
- 捕获语法错误，避免低级问题进入运行时
- 发现可疑逻辑，比如条件恒真、无用代码
- 检查未使用变量、重复导入、导入顺序
- 检查 React Hooks 使用是否符合规则
- 统一团队代码风格和最佳实践
常见文件：
.eslintrc.js：ESLint 主配置.eslintignore：声明不需要检查的目录，比如node_modules、build、dist
推荐在 package.json 中放统一命令：
{
"scripts": {
"lint": "eslint src --ext .js,.jsx",
"lint:fix": "eslint src --ext .js,.jsx --fix"
}
}
ESLint 的关键不是“规则越多越好”，而是团队先达成共识：哪些问题必须拦截，哪些问题可以警告，哪些规则要随着项目成熟逐步加强。
4. Prettier：把格式争论交给工具
Prettier 专注于代码外观的一致性，比如空格、换行、引号、逗号、行宽等。它不关心代码逻辑是否正确，这一点和 ESLint 要分清楚。
常见文件：
.prettierrc.js：格式化规则.prettierignore：跳过不需要格式化的文件
常见命令：
{
"scripts": {
"format": "prettier --write \"src/**/*.{js,jsx,css,less,md,json}\"",
"format:check": "prettier --check \"src/**/*.{js,jsx,css,less,md,json}\""
}
}
ESLint 和 Prettier 的搭配建议是：
- Prettier 管格式
- ESLint 管质量
- 使用
eslint-config-prettier关闭两者冲突的格式规则 - 必要时再用
eslint-plugin-prettier把格式问题暴露成 lint 问题
格式统一不是细节洁癖，而是团队协作效率的基础设施。
5. Stylelint + Less：样式也需要规范
CSS / Less 项目一大，常见问题就会出现：无效属性、样式顺序混乱、选择器层级过深、命名随意、变量散落在各处。Stylelint 就是样式层面的静态检查工具。
常见文件：
.stylelintrc.js：样式规则主配置.stylelintignore：忽略不检查的目录
Less 书写建议：
- 主题变量集中管理，比如
@primary-color - 减少深层嵌套
- 组件样式就近维护
- 命名尽量语义化
- 公共 mixin 和变量单独抽离
样式规范不是束缚，而是让 CSS / Less 也像业务代码一样可读、可维护。
6. CRACO：不 eject，也能改 CRA 的构建能力
Create React App 默认把 webpack、Babel、devServer 等配置隐藏起来。这样上手简单，但一旦项目需要路径别名、Less 主题变量、代理、loader、plugin，就会遇到“想改但不好改”的问题。
CRACO 的作用就是：在不 eject 的情况下，覆盖和扩展 CRA 的构建配置。
常见文件：
craco.config.js：CRACO 主配置craco-less.js：Less / 主题变量相关封装
使用 CRACO 后，package.json 里的脚本通常会从 react-scripts 改为 craco：
{
"scripts": {
"start": "craco start",
"build": "craco build",
"test": "craco test"
}
}
CRACO 常见用途：
- 配置 webpack alias，简化引用路径
- 接入 Less 和主题定制
- 调整 loader / plugin
- 配置 devServer / proxy
- 注入 Babel 插件
最佳实践是：构建相关改动集中在 CRACO 配置中，路径别名和 jsconfig.json 保持一致，升级 react-scripts 时做好兼容验证。
7. package.json / yarn.lock / .npmrc：项目能否稳定跑，很多时候就看它们
package.json 是项目中枢，描述项目基本信息、依赖、脚本命令、构建规则等。
重点关注：
scripts：团队统一的命令入口dependencies：生产运行依赖devDependencies：开发、构建、测试工具依赖browserslist：目标浏览器范围，影响打包和兼容性lint-staged/husky：可选的提交前检查配置
yarn.lock 的作用是锁定依赖精确版本，保证所有人、所有机器、所有 CI 安装到一致的依赖树。它应该提交到仓库，和代码一起管理。
.npmrc 常用于配置镜像源、安装策略和团队一致性。例如：
registry=https://registry.npmmirror.com
save-exact=true
strict-peer-dependencies=false
包管理的坑通常来自三件事：lock 文件被删、npm 和 yarn 混用、依赖装错位置。团队最好统一包管理器，并在文档里写清楚安装和升级流程。
8. 版本控制与协作文档：减少误提交和口口相传
.gitignore 决定哪些文件不应该进入仓库。常见忽略项包括：
node_modules/
build/
dist/
coverage/
.env.local
.DS_Store
*.log
不要提交它们的原因很简单：体积大、可再生成、可能包含敏感信息、不同机器生成内容不同、容易制造无意义冲突。
README.md 是新人打开项目后读到的第一份文档，建议包含：
- 项目简介
- 安装与启动命令
- 目录结构
- 环境变量说明
- 打包与部署方式
- 常见问题入口
其他团队文档可以按主题拆分：
QA.md：记录常见问题和排查方案LocalStorage.md：记录本地缓存 key、用途、过期策略AGENTS.md：团队或自动化代理的协作说明CLAUDE.md：AI 协作或项目特殊约定
文档不在多，在于准、在于新、在于真的被团队使用。
9. Dockerfile / Makefile / 部署脚本：把项目从本地带到环境里
Dockerfile 用来定义镜像构建步骤，目标是保证环境一致、部署可重复、迁移更便捷。
前端项目常见做法是多阶段构建：
- 第一阶段用 Node 安装依赖并打包
- 第二阶段用 nginx 提供静态资源服务
Makefile 则用于统一常用命令，减少记忆成本。例如：
install:
yarn install
build:
yarn build
docker-build:
docker build -t my-app .
docker-run:
docker run -p 80:80 my-app
部署脚本和部署文档通常会补充：
- 登录仓库
- 构建镜像
- 打标签
- 推镜像
- 重启服务
- 回滚方案
- 环境要求和依赖说明
容器化的本质不是“用了 Docker 就高级”，而是把复杂流程标准化，把确定性留给团队。
10. 自定义脚本与从零搭建清单
项目里经常会出现一些团队自定义脚本，例如：
extract-chine.js：提取中文文案，辅助国际化或文本审查myconfig.js：汇总团队自己的配置no-ds.js：关闭、过滤或绕过某些设计系统 / 构建规则checkNpm.js：检查 registry、Node / npm / yarn 版本、包名、发布规则等
这些脚本名字不一定“官方”，所以判断它们的方式不是看名字，而是看源码和 package.json scripts 里怎么调用。
如果从零搭建一个 React / CRACO 项目，可以按这个顺序来：
- 初始化项目
- 安装 React / react-dom / react-scripts 或基础脚手架
- 配置
package.json scripts - 配置
.editorconfig - 接入 ESLint + Prettier
- 接入 Stylelint
- 配置
jsconfig.json路径别名 - 需要时接入 CRACO + Less
- 配置
.env与.gitignore - 补充
README.md、QA.md、LocalStorage.md - 最后增加 Docker、Makefile、部署脚本
一个很实用的原则是：一开始不要把配置做得过重。先保证项目能跑，再逐步加规范；所有配置都配套 scripts 和文档；能自动化的就自动化，比如 lint、format、build、deploy。
总结
配置文件的本质，是把团队约定写进项目里。
.env 解决环境差异，.editorconfig 解决编辑器差异，ESLint / Prettier / Stylelint 解决代码与样式规范，CRACO 解决构建定制，package.json / lock 文件解决依赖一致性，文档解决协作成本，Docker 和部署脚本解决交付稳定性。
真正重要的不是“背配置”，而是理解每个配置文件要解决什么问题。理解了这一点，你就能把项目从“能跑”逐步建设成“可协作、可维护、可交付”的工程化项目。
