1. 从零到一为什么React工程化要从CRA开始如果你刚接触React或者从Vue、Angular等其他框架转过来面对的第一个问题往往是项目该怎么搭是手动配置Webpack、Babel、ESLint还是找个现成的脚手架我的建议很直接对于绝大多数新手和快速启动的项目直接用create-react-app简称CRA。这不是因为它最强大而是因为它最省心能让你把精力集中在学习React本身而不是被一堆构建工具的配置搞得焦头烂额。你可能听过一些声音说CRA“太重了”、“不够灵活”、“黑盒”。这些说法在特定场景下没错但对于入门和绝大多数业务项目来说CRA提供的“开箱即用”体验是无与伦比的。它背后是React官方团队维护集成了经过最佳实践验证的构建流水线。你不需要知道Webpack的entry和output怎么配也不需要纠结Babel该装哪些preset更不用手动设置开发服务器的热更新HMR。敲一行命令一个功能完整、配置合理的React开发环境就准备好了。更重要的是CRA隐藏了复杂性但并没有锁死你的出路。当你的项目成长到一定规模真的需要深度定制构建配置时CRA提供了“弹出”eject机制让你能拿到所有配置文件的完全控制权。但我的经验是90%的项目在整个生命周期内都不需要走到“弹出”那一步。CRA内置的配置和通过react-app-rewired或cracoCreate React App Configuration Override进行覆盖的能力已经足够应对大部分定制化需求。所以这篇内容的目标很明确我们不谈高深的原理就实实在在地带你走一遍用CRA创建、运行、理解一个React工程的全过程。你会知道文件该怎么组织脚本怎么用以及遇到常见问题时该怎么处理。咱们就从安装开始。2. 环境准备与项目创建避开第一个坑在敲下npx create-react-app my-app之前有几件小事需要确认好。这能帮你避免“一开始就卡住”的尴尬。2.1 基础环境检查Node.js与npmCRA依赖于Node.js环境。你首先需要确保电脑上已经安装了Node.js并且版本不要太旧。CRA通常对Node版本有要求比如需要Node 14或更高版本。打开你的终端Windows上是CMD或PowerShellMac/Linux上是Terminal输入以下命令检查node -v npm -v如果显示了版本号比如v18.17.0和9.6.7那就没问题。如果提示“命令未找到”那你需要先去Node.js官网下载安装包。我个人的习惯是使用nvmNode Version Manager来管理Node版本这样可以很方便地在不同项目间切换版本但对于新手直接安装官网的LTS长期支持版是最稳妥的。注意尽量避免使用操作系统自带的包管理器如apt、yum安装的Node版本可能过旧且路径容易出问题。从官网下载安装是通用性最好的方法。2.2 选择包管理工具npm, yarn, 还是 pnpmCRA支持多种包管理工具。传统上它使用npm。但你也可以选择yarn或pnpm它们在某些情况下可能有更快的速度或更优的磁盘空间利用。npmNode.js自带的无需额外安装最通用。yarn由Facebook推出曾经以速度和确定性安装著称。现在npm 6版本在速度上已经追平很多。pnpm采用硬链接方式能极大节省磁盘空间安装速度也很快尤其适合电脑上有多个大型前端项目的同学。对于新手我建议先用npm减少学习成本。如果你已经安装了yarn或pnpmCRA的命令会自动检测并使用它们。为了演示我们后续命令都以npm为例。2.3 执行创建命令理解npx的作用这是最关键的一步。以前你需要全局安装create-react-app这个包npm install -g create-react-app create-react-app my-app但现在更推荐也最标准的方式是使用npx。npx是npm 5.2版本后自带的一个工具。它的作用是临时下载并运行指定的npm包运行完后就会清理掉避免全局安装带来的版本冲突问题。所以请打开终端进入你希望创建项目的目录比如~/Documents或D:\projects然后运行npx create-react-app my-react-app这里的my-react-app是你的项目名称你可以换成任何你喜欢的名字但建议使用小写字母和连字符kebab-case这是社区常见的命名约定。当你按下回车后终端会开始工作。你会看到它正在下载一个临时的create-react-app包然后开始创建项目。这个过程会做几件事创建一个名为my-react-app的文件夹。在这个文件夹内初始化一个新的Git仓库如果你不需要可以后续删除.git文件夹。安装React、ReactDOM以及所有开发依赖Webpack, Babel, ESLint等。生成项目的基础文件和目录结构。这个过程会花费几分钟取决于你的网络速度。期间可能会有一个选择package管理器的提示直接按回车选择默认的npm即可。2.4 可能遇到的问题与解决网络超时或下载缓慢这通常是因为npm registry的访问问题。你可以尝试切换为国内镜像源。对于npm可以执行npm config set registry https://registry.npmmirror.com创建完成后可以再切回官方源npm config set registry https://registry.npmjs.org权限错误Permission denied在Mac/Linux上如果之前用sudo安装过全局包可能会导致权限问题。尽量不要用sudo来执行npx create-react-app。如果遇到问题可以尝试修复npm默认目录的权限或者使用npx create-react-app my-app --use-npm明确指定。项目名称冲突如果提示目录已存在要么换一个名字要么删除已存在的空目录。当终端最后出现“Happy hacking!”之类的成功提示并且光标重新可以输入时就说明项目创建成功了。3. 项目结构深度解析每个文件是干什么的进入项目目录cd my-react-app然后用你的代码编辑器比如VSCode打开它。你会看到类似下面的结构my-react-app/ ├── node_modules/ ├── public/ │ ├── favicon.ico │ ├── index.html │ ├── logo192.png │ ├── logo512.png │ ├── manifest.json │ └── robots.txt ├── src/ │ ├── App.css │ ├── App.js │ ├── App.test.js │ ├── index.css │ ├── index.js │ ├── logo.svg │ ├── reportWebVitals.js │ └── setupTests.js ├── .gitignore ├── package-lock.json ├── package.json └── README.md别被文件数量吓到我们一个个拆解你只需要重点关注其中几个。3.1package.json项目的“身份证”和“说明书”这是整个项目的核心配置文件必须彻底理解。{ name: my-react-app, version: 0.1.0, private: true, dependencies: { testing-library/jest-dom: ^5.17.0, testing-library/react: ^13.4.0, testing-library/user-event: ^13.5.0, react: ^18.2.0, react-dom: ^18.2.0, react-scripts: 5.0.1, web-vitals: ^2.1.4 }, scripts: { start: react-scripts start, build: react-scripts build, test: react-scripts test, eject: react-scripts eject }, eslintConfig: { extends: [ react-app, react-app/jest ] }, browserslist: { production: [ 0.2%, not dead, not op_mini all ], development: [ last 1 chrome version, last 1 firefox version, last 1 safari version ] } }dependencies项目运行所依赖的包。react和react-dom是核心库。react-scripts是CRA的灵魂它封装了Webpack、Babel、ESLint、Jest等所有构建和测试工具。你不需要直接配置它们react-scripts都帮你搞定了。scripts定义了你可以运行的命令。npm start启动开发服务器在localhost:3000实时预览支持热更新。npm run build将项目打包优化生成用于生产环境的build文件夹。npm test运行Jest测试。npm run eject这是一个单向操作它会将react-scripts的所有配置“弹射”出来变成你项目根目录下的config和scripts文件夹。之后你需要自己维护Webpack等配置。除非你非常确定需要深度定制否则不要轻易执行。browserslist指定项目要兼容的浏览器范围。production环境目标更广development环境则针对最新版浏览器以提升开发体验。这个配置会被Autoprefixer自动添加CSS前缀等工具使用。3.2public/与src/静态资源与源代码的分离这是前端项目常见的分离方式。public/目录存放静态资源这些文件会被直接复制到最终构建产物的根目录。index.html页面入口模板。CRA的Webpack会自动将打包好的JavaScript和CSS文件注入到这里。注意看其中的div idroot/div这就是React应用挂载的根节点。一般我们不会直接修改这个文件除非要添加外部CDN的JS库或修改title。manifest.jsonPWA渐进式Web应用的配置文件定义了应用名称、图标等。robots.txt告诉搜索引擎爬虫哪些页面可以抓取。src/目录存放所有源代码是我们主要工作的地方。index.jsJavaScript入口文件。它导入了React和ReactDOM导入了根组件App然后通过ReactDOM.createRoot方法将App组件渲染到index.html中那个idroot的DOM节点上。这是React 18的推荐写法。App.js根组件。这是你看到的网页内容的起点。一个标准的函数组件。App.css和index.css样式文件。index.css是全局样式App.css是App组件的局部样式在React中CSS默认是全局的但CRA配置了CSS Modules等功能可以模拟局部作用域。App.test.js针对App组件的测试文件使用Jest和React Testing Library。setupTests.js测试文件的初始化配置比如这里默认导入了testing-library/jest-dom的扩展断言。3.3 其他文件node_modules/所有依赖包都安装在这里体积巨大务必在.gitignore中忽略它。.gitignore告诉Git哪些文件或目录不需要纳入版本管理比如node_modules、build、.env等。README.md项目的说明文档CRA已经为你生成了一个基础版本。理解了这个结构你就知道代码该往哪里放了组件通常放在src/components/你需要自己创建这个文件夹页面放在src/pages/工具函数放在src/utils/以此类推。良好的目录组织是项目可维护性的第一步。4. 开发、构建与测试三大核心脚本实战创建好项目理解了结构接下来就是让它跑起来。CRA通过package.json里的scripts提供了三个最常用的命令。4.1npm start启动开发服务器在项目根目录下运行npm start或者yarn start几秒钟后你的默认浏览器会自动打开http://localhost:3000显示那个旋转的React logo页面。这个开发服务器基于Webpack Dev Server提供了以下关键特性热模块替换HMR当你修改并保存src/目录下的文件时浏览器页面会无刷新更新状态比如你在输入框里打的字会被保留。这极大地提升了开发效率。你可以马上试试打开src/App.js把“Learn React”改成“Learn React Quickly”保存看看浏览器。错误覆盖层Overlay如果你的代码有语法错误或运行时错误浏览器页面上会显示一个错误覆盖层清晰地指出错误文件和行号而不是只在控制台输出晦涩的信息。ESLint集成代码规范问题也会实时显示在终端和浏览器覆盖层中如果配置了的话。网络代理你可以在package.json中添加proxy字段来解决前端开发时的跨域问题将API请求代理到后端服务器。开发服务器会一直运行直到你在终端按CtrlC停止它。4.2npm run build生成生产环境代码当你的应用开发完成需要部署到线上时就需要构建。npm run build这个命令会启动一个优化的构建过程代码转换与打包Babel将JSX和最新的JavaScript语法转换为浏览器广泛兼容的ES5代码。Webpack将项目中所有模块JS、CSS、图片打包成少数几个文件通常是一个或多个JS块和一个CSS文件。代码压缩与优化使用TerserPlugin压缩JavaScript使用CssMinimizerPlugin压缩CSS移除所有注释、空白符进行变量名混淆在保证功能的前提下显著减小文件体积。静态资源处理小于一定体积的图片会被转换成Base64内联更大的图片会被复制到build/static/media/目录下并生成哈希文件名用于长期缓存。生成build目录所有优化后的文件都会输出到build目录。这个目录就是你可以直接部署到任何静态文件托管服务如Netlify, Vercel, GitHub Pages或你自己的Nginx服务器的内容。构建完成后你可以本地预览生产版本npx serve -s buildserve是一个小型静态文件服务器。-s参数代表如果请求的不是一个文件比如前端路由的/about路径就返回index.html单页应用SPA必需。这样你就能在本地模拟线上环境检查应用。重要提示构建出的文件路径默认是绝对路径/static/js/main.xxx.js。如果你需要部署到子路径如https://yourname.github.io/your-repo/需要在package.json中设置homepage: .或具体的URL前缀然后重新构建。4.3npm test运行测试套件CRA集成了Jest作为测试运行器并默认配置了React Testing Library用于组件测试。npm test运行此命令会进入交互式测试监视模式。Jest会监控你的文件变化当有.test.js或.spec.js文件被修改时会自动重新运行相关的测试。在监视模式下你可以按提示进行一些操作按a运行所有测试。按f只运行上次失败的测试。按q退出监视模式。按Enter触发一次测试运行。默认生成的App.test.js是一个简单的快照测试和元素断言测试。随着项目复杂你会编写更多测试来保证代码质量。测试文件通常和被测组件放在同一目录方便管理。5. 超越默认配置如何定制你的CRA项目CRA默认配置能满足大部分需求但总有需要微调的时候。记住一个原则在弹出eject之前先尝试其他覆盖配置的方法。5.1 环境变量管理不同环境的配置CRA内置了环境变量的支持。你可以在项目根目录创建以下文件.env默认所有环境都加载。.env.local本地覆盖不会提交到Git。.env.development,.env.test,.env.production特定环境加载。.env.development.local等特定环境的本地覆盖。在这些文件中定义以REACT_APP_开头的变量REACT_APP_API_URLhttps://api.myapp.com REACT_APP_VERSION1.0.0在JavaScript代码中可以通过process.env.REACT_APP_API_URL来访问。构建时这些变量会被直接替换为对应的字符串值。5.2 使用craco或react-app-rewired覆盖配置这是最推荐的进阶定制方式。以craco为例安装依赖npm install craco/craco在项目根目录创建craco.config.js文件。修改package.json中的scripts将react-scripts替换为cracoscripts: { start: craco start, build: craco build, test: craco test }现在你就可以在craco.config.js里覆盖Webpack、Babel等配置了。例如添加一个路径别名来简化导入// craco.config.js const path require(path); module.exports { webpack: { alias: { : path.resolve(__dirname, src), }, }, };之后在代码中你就可以用import Button from /components/Button来代替import Button from ../../components/Button。craco有丰富的插件生态系统可以让你轻松集成Tailwind CSS、Ant Design、修改Babel插件等而无需弹出。5.3 最后的“核按钮”npm run eject如前所述这是一个单向、不可逆的操作。执行后你会永久移除项目对react-scripts的单点依赖。所有构建配置Webpack, Babel, ESLint等都会复制到项目的config/和scripts/目录下。package.json中的依赖会暴增因为原来隐藏在react-scripts里的所有依赖现在都变成了你的直接依赖。除非你团队有专门的基建人员并且你明确知道CRA的默认配置无法满足你的需求例如需要自定义复杂的Webpack loader或插件否则请谨慎使用eject。一旦弹出你将需要自己负责所有构建工具的升级和问题排查。6. 从CRA工程出发下一步学什么当你成功运行起CRA项目后就算是正式踏入了React开发的大门。但这个空项目只是一个起点。接下来我建议你按这个顺序去充实和深入学习理解组件与JSX彻底搞懂App.js里的函数组件怎么写JSX语法如何混合JavaScript和HTML-like标签。这是React的基石。学习状态管理从useStateHook开始理解组件内部状态。然后学习useEffect处理副作用数据获取、订阅等。组件通信与组合学习如何通过props向子组件传递数据和回调函数以及如何使用childrenprop进行组件组合。路由管理引入react-router-dom库为你的应用添加多个页面和导航功能。状态提升与Context当多个组件需要共享状态时学习将状态提升到共同的父组件或者使用React.createContext进行跨层级数据传递。探索状态管理库对于更复杂的应用可以考虑引入Zustand、Redux Toolkit或Recoil等专门的状态管理库。样式方案尝试不同的CSS方案如CSS Modules、Styled-components、Emotion或Utility-First的Tailwind CSS找到适合你和团队的风格。HTTP客户端学习使用fetchAPI或更强大的库如axios来与后端API交互。性能优化了解React.memo、useMemo、useCallback以及代码分割React.lazy Suspense来优化应用性能。记住CRA为你扫清了工程配置的障碍让你能专注于React本身的学习和业务逻辑的开发。随着你技能的提升你会逐渐理解CRA背后那些工具的作用那时再根据实际需求去定制它们就会水到渠成。现在就从修改src/App.js写出你的第一个组件开始吧。