Create React App 完全指南：零配置创建 React 应用
【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app
[!CAUTION]弃用说明（Deprecated）：Create React App 是 2017—2021 年间快速搭建 React 项目的关键工具之一，目前项目已进入长期停滞维护（long-term stasis）状态。官方建议迁移到 Start a New React Project 编写，用于理解该工具的设计哲学、使用方式与源码实现。
快速上手：三行命令启动一个 React 应用
npx create-react-app my-app cd my-app npm startnpx随 npm 5.2+ 附带，无需预先安装create-react-app；- 如果你之前通过
npm install -g create-react-app全局安装过旧版本，建议先执行npm uninstall -g create-react-app或yarn global remove create-react-app卸载，确保npx始终拉取最新版本； - 启动后浏览器访问 http://localhost:3000/ 即可看到应用；
- 需要发布到生产环境时，执行
npm run build生成压缩后的生产包。
环境要求：本机需要Node 14.0.0 或更高版本（服务器上无需安装），建议使用最新的 LTS 版本。可用 nvm），
react-scripts同样要求"node": ">=14.0.0"（见 packages/react-scripts/package.json）。
Get Started Immediately：无需任何构建配置
使用 CRA 创建项目时，不需要安装或配置 webpack、Babel 等构建工具——它们已被预先配置好并隐藏起来，你只需专注于写业务代码。这也是 CRA 的核心卖点：创建一个项目，直接开写。
创建应用的四种方式
| 工具 | 命令 | 版本要求 |
|---|---|---|
| npx | npx create-react-app my-app | npm 5.2+ |
| npm | npm init react-app my-app | npm 6+（npm init <initializer>） |
| Yarn | yarn create react-app my-app | Yarn 0.25+（yarn create <starter-kit-package>） |
三种方式都会在当前目录下创建名为my-app的目录，并生成初始项目结构与安装传递依赖。
生成的目录结构
创建完成后，my-app目录结构如下：
my-app ├── README.md ├── node_modules ├── package.json ├── .gitignore ├── public │ ├── favicon.ico │ ├── index.html │ └── manifest.json └── src ├── App.css ├── App.js ├── App.test.js ├── index.css ├── index.js ├── logo.svg ├── serviceWorker.js └── setupTests.js无复杂配置或繁琐目录结构，只包含构建应用所需的文件。安装完成后进入项目目录即可开始开发。
从源码看模板如何落地
README 中展示的目录结构，对应仓库中的模板包 packages/cra-template/template（JS 模板）与 packages/cra-template-typescript/template（TS 模板）。模板的生效链路如下：
create-react-app的 createReactApp.js 中的run()函数解析出要安装的react-scripts版本与模板包（getTemplateInstallPackage默认返回cra-template，见 L629-L674）；- 安装完成后，通过
executeNodeScript调用react-scripts/scripts/init.js； init.js读取模板包内template.json（见 packages/cra-template/template.json，其package字段声明了@testing-library/*、web-vitals等依赖与eslintConfig），并将template/目录整体拷贝到项目根目录（对应fs.copySync(templateDir, appPath)，见 init.js）；- 同时合并生成项目
package.json的scripts（start/build/test均指向react-scripts对应命令，见 init.js）、eslintConfig（extends: 'react-app'）与browserslist。
注：README 生成示例中的
serviceWorker.js属于旧版模板；当前仓库模板已改为reportWebVitals.js（PWA 的 Service Worker 自react-scripts@2.0.0起改为按需启用）。
内置命令详解
进入新创建的项目后，可以运行以下内置命令（均定义在react-scripts的 bin 入口 packages/react-scripts/bin/react-scripts.js 中，它会将start/build/test/eject分发到 packages/react-scripts/scripts 下对应的脚本文件）。
npm start/yarn start— 开发模式
以开发模式运行应用，浏览器访问 http://localhost:3000 查看：
- 热更新：修改代码后页面自动刷新（实际由
react-refresh提供 Fast Refresh 能力，见 packages/react-scripts/package.json 中的react-refresh依赖）； - 错误提示：构建错误与 lint 警告会显示在控制台，同时在浏览器中以全屏错误浮层呈现。
从源码看（scripts/start.js），脚本首先设置BABEL_ENV=development与NODE_ENV=development，默认端口为process.env.PORT || 3000（L55），默认绑定0.0.0.0；若端口被占用，会调用choosePort自动询问并使用下一个可用端口。
npm test/yarn test— 交互式测试
以交互模式运行测试监听器，默认只运行自上次提交以来有变更文件相关的测试，配合 jest 的 watch 模式实现增量测试。
npm run build/yarn build— 生产构建
将应用构建到build目录：
- 以 React production 模式正确打包，并对构建做最佳性能优化（脚本先设置
NODE_ENV=production，见 scripts/build.js）； - 产物经过压缩，文件名包含内容哈希（便于长期缓存与增量发布）；
- 构建完成后即进入可部署状态。
从源码看，构建使用了terser-webpack-plugin做压缩、mini-css-extract-plugin提取 CSS、workbox-webpack-plugin生成 Service Worker（均见 packages/react-scripts/package.json 的依赖列表），并通过FileSizeReporter输出各 bundle 的 gzip 体积报告（build.js）。
User Guide 与版本更新
- 关于 CRA 的详细用法与大量技巧，参见其官方文档（User Guide）；
- 版本更新相关指引同样见 User Guide 的 "updating-to-new-releases" 章节。
设计哲学（Philosophy）
CRA 的三大设计原则：
- 单一依赖（One Dependency）：整个项目只有一个构建依赖。底层虽使用 webpack、Babel、ESLint 等优秀项目，但 CRA 在其之上提供了内聚、精选（curated）的一体化体验；
- 零配置（No Configuration Required）：无需配置任何东西，开发与生产构建都已被合理配置好，你可以专注于写代码；
- 无锁定（No Lock-In）：任何时刻都可以 "eject" 到自定义配置——执行一条命令，所有配置与构建依赖直接迁移进你的项目，从上次的进度继续。
Eject：从源码理解"无锁定"
eject由 packages/react-scripts/scripts/eject.js 实现：它会将config/目录下的 webpack 配置、scripts/下的启动脚本以及所有构建依赖写入项目，并把package.json的scripts从react-scripts start改为直接调用本地脚本。权衡是：这些工具被预配置成特定方式工作，如果项目需要更多自定义，可以 eject 后自行维护配置——代价是后续需要自己维护这份配置。
内置能力（What's Included）
创建的应用开箱即用，涵盖构建现代单页 React 应用所需的全部能力：
- React、JSX、ES6、TypeScript 与 Flow 语法支持（TS 通过
--template typescript或cra-template-typescript模板启用）； - ES6 之外的语言扩展，如对象展开运算符（object spread）；
- 自动添加 CSS 前缀（Autoprefixed CSS），无需手写
-webkit-等前缀（由postcss-preset-env实现，见 packages/react-scripts/package.json）； - 快速交互式单元测试运行器，内置覆盖率报告支持；
- 实时开发服务器，对常见错误给出警告；
- 生产构建脚本：打包 JS、CSS 与图片，带哈希与 sourcemap；
- 离线优先的 Service Worker 与 Web App Manifest，满足 PWA 标准（注意：Service Worker 自
react-scripts@2.0.0起为按需启用（opt-in））； - 上述工具通过单一依赖轻松升级。
从源码确认这些能力对应的关键依赖：babel-preset-react-app（Babel 预设，含 JSX/TS/Flow 支持）、postcss-preset-env（自动前缀）、workbox-webpack-plugin（PWA/Service Worker）、webpack-dev-server（开发服务器）、jest（测试运行器），均见 packages/react-scripts/package.json 的依赖清单。
CLI 参数与高级用法（源码级补充）
尽管 README 未展开，但从 createReactApp.js 的 CLI 定义可确认以下参数（执行npx create-react-app --help可见完整说明）：
| 参数 | 说明 |
|---|---|
<project-directory> | 必填，项目目录名 |
--verbose | 打印额外日志 |
--info | 打印环境调试信息（OS/CPU、Node/npm/Yarn 版本、浏览器版本、react/react-dom/react-scripts 版本等，由envinfo收集） |
--scripts-version <package> | 使用非标准版本的 react-scripts，支持：具体 npm 版本（如0.8.2）、npm tag（如@next）、npm 上的 fork（如my-react-scripts）、本地路径（file:../my-react-scripts）、.tgz/.tar.gz归档地址 |
--template <path> | 指定项目模板，支持：npm 上的自定义模板（如cra-template-typescript）、本地路径（file:../my-custom-template）、.tgz/.tar.gz归档 |
--use-pnp | 使用 Yarn Plug'n'Play（需 Yarn 1.12+；npm 不支持 PnP 时会回退常规安装） |
源码中getTemplateInstallPackage（L629-L674）还会对模板名做规范化：自动为未加前缀的模板名补上cra-template-前缀并保留@scope/与@version信息；getInstallPackage（L579-L627）则负责将--scripts-version解析为可安装的包名。
此外，创建过程包含多层校验与兜底：
- Node 版本检查：
createApp中若 Node 低于 14，会回退使用旧版react-scripts@0.9.x并给出警告（L267-L283）；安装后checkNodeVersion还会核对 react-scripts 的engines.node（L822-L851）； - 项目名校验：
checkAppName使用validate-npm-package-name校验命名，并禁止使用react、react-dom、react-scripts作为项目名（L853-L888）； - 目录安全检测：
isSafeToCreateProjectIn会检查目标目录中是否存在冲突文件（L938-L1008）； - 失败清理：安装失败时自动删除生成的
package.json、node_modules，若目录为空则连目录一并删除（L537-L575）。
何时选择其他工具（Popular Alternatives）
CRA 适合的场景：
- 学习 React——在舒适且功能丰富的开发环境中学习；
- 启动新的单页 React 应用；
- 为你的库和组件创建 React 示例。
以下场景建议考虑其他方案：
- 只想试玩 React、不想引入成百上千的传递构建依赖：考虑用单个 HTML 文件或在线沙箱；
- 需要将 React 集成到服务端模板框架（如 Rails、Django、Symfony），或不是构建单页应用：考虑 nwb、Neutrino（Rails 可用 Rails Webpacker，Symfony 可用 webpack Encore）；
- 需要发布 React 组件：nwb 或 Neutrino 的 react-components preset 也可以胜任；
- 需要服务端渲染：考虑 Next.js 或 Razzle——CRA 对后端无感知，只产出静态 HTML/JS/CSS 产物；
- 网站以静态内容为主（如作品集、博客）：考虑 Gatsby 或 Next.js——Gatsby 在构建时将网站预渲染为 HTML，Next.js 同时支持服务端渲染与预渲染；
- 需要更多定制：考虑 Neutrino 及其 React preset。
上述工具都可在零配置或极少配置下工作；如果你更愿意自己配置构建，也可以参考官方 "add React to a website" 指南。
相关生态与参与贡献
- React Native：寻找类似 CRA 的 RN 方案，可关注 Expo CLI；
- 贡献：参见 CONTRIBUTING.md；
- 许可：CRA 以 MIT 协议开源（见 LICENSE）。
在仓库中进一步探索
本文基于仓库 README.md 编写，涉及的核心实现可继续阅读：
- CLI 主入口与创建流程：packages/create-react-app/createReactApp.js
- react-scripts 命令分发：packages/react-scripts/bin/react-scripts.js
- 开发/构建/测试脚本：packages/react-scripts/scripts/start.js、packages/react-scripts/scripts/build.js、packages/react-scripts/scripts/test.js
- 项目初始化与模板落地：packages/react-scripts/scripts/init.js
- 内置依赖清单：packages/react-scripts/package.json
- JS/TS 模板：packages/cra-template/template、packages/cra-template-typescript/template
- 模板依赖声明：packages/cra-template/template.json
【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
