Create-React-App (CRA) logo

Create-React-App (CRA)

React 官方旧式脚手架工具，由 Meta（Facebook）团队创建，曾一度是 React 生态的核心基础设施。

React构建工具脚手架Webpack

Create React App 是 Meta 推出的零配置 React 项目脚手架工具，封装了 Webpack 4、Babel、ESLint 等工具链。2025 年 2 月已正式废弃，官方推荐迁移到 Vite、Next.js 等现代方案。

访问官网

Create-React-App (CRA)

React 官方旧式脚手架工具，由 Meta（Facebook）团队创建，曾一度是 React 生态的核心基础设施。2025 年 2 月，React 团队正式发布「Sunsetting Create React App」公告，宣告 CRA 进入废弃（Deprecated）状态，进入维护模式，不再接受新功能。官方明确推荐使用 Vite、Next.js、React Router、Rsbuild 等现代替代方案。

技术简介说明

Create React App 是 Facebook（现 Meta）团队于 2016 年推出的官方 React 项目脚手架工具，旨在解决早期 React 开发者在搭建项目时面临的 Webpack、Babel、ESLint 等复杂工程化配置难题。通过一行命令 npx create-react-app my-app，开发者即可获得一个开箱即用的 React 项目，内建开发服务器、热更新（Hot Reload）、自动化构建、代码分割、ES6+ 转译、JSX 支持等现代前端能力，让开发者能够专注于业务代码本身，而非工具链配置。

在其鼎盛时期（2017–2022 年），CRA 是 React 生态中使用最广泛的项目初始化工具，几乎成为 React 入门教程、官方文档和技术书籍的默认起点。它的"零配置"理念深刻影响了前端脚手架的设计范式，被广泛模仿和借鉴。CRA 封装了 Webpack 4、Babel 7、ESLint、PostCSS、Jest 等工具，通过 react-scripts 包统一管理，避免了版本碎片化问题，让数百万 React 项目得以快速启动。

然而，随着前端工程化技术快速演进，CRA 的局限性日益凸显：底层 Webpack 构建速度缓慢、无法灵活自定义配置（除非 eject）、不支持现代 HMR 方案（如 ESM-based HMR）、对 TypeScript 支持不够完善、开发体验落后于 Vite 等新一代工具。2023 年起，CRA 的实际维护已基本停滞；2025 年 2 月 14 日，React 团队在 react.dev 官方博客正式发布公告，宣布 CRA 废弃，并发布了对 React 19 兼容的最后一次维护版本。存量项目仍然可以运行，但新项目应全面转向 Vite、Next.js 或 Rsbuild 等现代方案。

基本信息

快速上手

安装

# 使用 npx 创建项目（推荐方式，无需全局安装）
npx create-react-app my-app
 
# 使用 yarn
yarn create react-app my-app
 
# 使用 pnpm
pnpm create react-app my-app
 
# 进入项目目录
cd my-app
 
# 启动开发服务器
npm start
 
# 构建生产版本
npm run build
 
# 运行测试
npm test
 
# eject（不可逆操作）
npm run eject

⚠️ 警告：由于 CRA 已废弃，新建项目执行 npx create-react-app 时会触发废弃警告提示。官方强烈建议新项目使用 create-vite、Next.js 或其他现代方案。

基础配置

CRA 遵循「零配置」原则，所有工具链配置封装在 react-scripts 包内部，开发者无需手动管理 Webpack、Babel 等配置文件。项目创建后，package.json 中包含以下核心脚本：

{
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "browserslist": {
    "production": [">0.2%", "not dead", "not op_mini all"],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

若需自定义配置而不使用 eject，可通过在根目录创建以下文件进行有限覆盖：

  • .env / .env.local / .env.production — 环境变量
  • jsconfig.json — JavaScript/路径别名配置
  • setupTests.js — 测试初始化配置
  • src/setupProxy.js — 开发代理配置（需安装 http-proxy-middleware）

最小示例

// src/App.js
import React from 'react';
 
function App() {
  return (
    <div className="App">
      <h1>Hello, Create React App!</h1>
      <p>这是一个最小的 React 应用示例。</p>
    </div>
  );
}
 
export default App;
// src/index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
 
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

核心概念与架构

Webpack 封装

CRA 的核心架构基于 Webpack 4 的深度封装。react-scripts 包内嵌了完整的 Webpack 配置，包括开发模式下的 webpackDevServer 和生产模式下的生产构建流程。开发者不直接接触 Webpack 配置文件，所有打包、代码分割、Tree Shaking、CSS 处理、资源加载等逻辑均由 react-scripts 内部维护。这种设计的优势是降低了入门门槛，劣势是当需要自定义时，灵活性严重不足。

react-scripts

react-scripts 是 CRA 的核心运行时包，封装了以下职责：

  • Webpack 开发服务器配置（devServer、热更新、代理）
  • 生产构建流程（代码分割、资源哈希、CSS 提取）
  • Babel 预设配置（babel-preset-react-app）
  • ESLint 配置（eslint-config-react-app）
  • Jest 测试运行器封装
  • TypeScript 支持（通过 typescript 包自动检测）

所有版本升级通过 npm install react-scripts@latest 统一管理，避免了各项目之间工具链版本碎片化的问题。

eject 机制

npm run eject 是 CRA 提供的"逃生出口"——执行后将 react-scripts 内所有封装的 Webpack 配置、Babel 配置、ESLint 配置、脚本文件全量展开到项目根目录，开发者可完全自定义。但 eject 是一个不可逆操作：一旦执行，无法回退到 react-scripts 管理模式，后续版本升级也无法自动进行。这一机制虽然满足了高级自定义需求，但也导致了大量项目陷入"配置债务"，是 CRA 架构设计中最受争议的部分。

Babel 转译

CRA 使用 babel-preset-react-app 预设，集成了 @babel/preset-env、@babel/preset-react、@babel/preset-typescript 以及多个插件（如 @babel/plugin-transform-runtime、babel-plugin-macros 等）。开发者可通过 .babelrc 或 babel.config.js 配合 babel-plugin-macros 实现有限的 Babel 扩展，但完整的 Babel 配置自定义只能通过 eject 实现。

环境变量管理

CRA 使用 dotenv（.env 文件）管理环境变量，仅暴露以 REACT_APP_ 为前缀的变量给前端代码，防止服务器端敏感信息泄露。在构建时，环境变量通过 Webpack 的 DefinePlugin 静态替换到代码中。这种方式简单直接，但无法实现运行时动态环境变量，也不支持按环境精细分层管理。

核心特性

  1. 零配置启动：一行命令创建项目，无需手动编写 Webpack、Babel、ESLint 配置，开箱即用的开发服务器和生产构建流程，极大降低了 React 入门门槛。

  2. 内建开发服务器：基于 Webpack Dev Server，支持自动编译、浏览器热更新（Fast Refresh）、代理配置（setupProxy.js）等功能，提供流畅的开发体验。

  3. 自动化生产构建：执行 npm run build 后，自动完成代码分割、Tree Shaking、资源哈希命名、CSS 提取、JS 压缩、HTML 注入等优化，生成可直接部署的静态文件。

  4. 内建 Jest 测试集成：react-scripts test 封装了 Jest 测试运行器，支持 --watch 模式、覆盖率收集、ES6+ 语法转译，零配置即可运行单元测试和集成测试。

  5. TypeScript 自动支持：创建项目时使用 .tsx / .ts 文件，或在项目中安装 typescript 包后，CRA 自动检测并启用 TypeScript 编译支持，无需手动配置 tsconfig.json（但可自定义）。

  6. CSS 模块化与预处理器支持：支持 CSS Modules（*.module.css）、Sass/SCSS（需安装 sass 包）、Less（需安装 less 包，社区支持）等，CSS 处理逻辑内置于 Webpack 配置中。

  7. ESLint 静态检查：内置 eslint-config-react-app，基于 eslint-plugin-react、eslint-plugin-react-hooks 等规则，提供 React 最佳实践的代码检查，开发时实时报错提示。

  8. Service Worker 与 PWA 支持：通过 workbox-webpack-plugin 预置了 Service Worker 生成能力，配合 src/serviceWorker.js 可快速将应用改造为 PWA（渐进式 Web 应用），支持离线访问。

  9. 路径别名与绝对导入：通过 jsconfig.json 或 tsconfig.json 配置 baseUrl，支持以 src/ 为基准的绝对导入，避免深层相对路径（../../../）。

  10. Browserslist 集成：通过 package.json 中的 browserslist 字段控制目标浏览器范围，影响 Babel 转译策略、Autoprefixer 前缀生成和构建产物的兼容性。

生态图

create-react-app（CLI 入口）
├── react-scripts（核心脚本包，封装 Webpack/Babel/Jest 配置）
│   ├── babel-preset-react-app（Babel 预设）
│   ├── eslint-config-react-app（ESLint 配置预设）
│   ├── react-dev-utils（开发工具：错误覆盖、文件监听、浏览器启动）
│   ├── webpack（内嵌 Webpack 4）
│   ├── babel-loader
│   ├── css-loader / style-loader / postcss-loader
│   ├── jest / jest-environment-jsdom
│   └── workbox-webpack-plugin（PWA 支持）
├── create-react-app（脚手架创建命令）
├── eslint-config-react-app（独立发布，可单独使用）
├── react-error-overlay（开发时浏览器内错误覆盖层）
└── confusable-homoglyphs（依赖工具）

与 React 生态其他工具的关联：

  • React Router：CRA 不内置路由，需手动安装 react-router-dom
  • Redux Toolkit：官方推荐状态管理方案，需额外安装
  • Testing Library：CRA 默认使用 @testing-library/react 作为测试工具
  • Next.js / Remix：CRA 的"替代品"，提供框架级解决方案

适用场景

仍然适用的场景

  • 遗留项目维护：大量 2017–2023 年创建的 React 项目仍运行在 CRA 上，维护这些项目需要理解其架构和配置方式。
  • 快速原型验证：对构建性能无要求的简单原型、demo 或内部工具，CRA 的零配置仍有快速启动优势。
  • 学习 React 基础：部分入门教程仍使用 CRA，理解 CRA 有助于跟进这些学习资源。
  • 已 eject 的稳定项目：已执行 eject 并深度自定义配置的项目，短期内迁移成本高，可继续维护。

不推荐使用的场景

  • 任何新项目：官方已明确废弃，不应在新项目中使用。
  • 需要 SSR/SSG 的项目：CRA 仅支持客户端渲染（CSR），无法实现服务端渲染或静态生成。
  • 大型生产应用：Webpack 4 构建速度慢，缺乏现代代码分割和路由集成方案。
  • 需要 TypeScript 深度集成的项目：CRA 对 TypeScript 的支持相对基础，无法自定义 tsconfig.json 的编译选项（除非 eject）。
  • 追求极致开发体验的项目：Vite 的 ESM 原生 HMR 速度远超 CRA 的 Webpack HMR。

开发与工程化

开发流程

# 1. 启动开发服务器（默认 http://localhost:3000）
npm start
 
# 2. 代码编辑，自动热更新（Fast Refresh）
 
# 3. 运行测试
npm test                    # 交互模式
npm test -- --coverage      # 覆盖率报告
npm test -- --watchAll      # 监听所有文件
 
# 4. 代码检查（CRA 内建 ESLint）
# 开发时浏览器控制台实时显示 lint 错误
 
# 5. 配置代理（开发环境 API 转发）
# 安装 http-proxy-middleware
npm install http-proxy-middleware --save-dev
 
# 创建 src/setupProxy.js
# const { createProxyMiddleware } = require('http-proxy-middleware');
# module.exports = function(app) {
#   app.use('/api', createProxyMiddleware({ target: 'http://localhost:8080' }));
# };

构建与部署

# 构建生产版本
npm run build
 
# 构建产物输出到 build/ 目录
# 包含：
#   - 静态资源（JS/CSS/图片）带内容哈希文件名
#   - index.html 自动注入资源引用
#   - asset-manifest.json 资源清单
 
# 部署到静态托管服务
# 方式1：部署到 Vercel / Netlify / Cloudflare Pages（直接连接 Git 仓库）
# 方式2：部署到 Nginx / Apache（需配置 SPA fallback）
# 方式3：部署到 GitHub Pages
#   安装 gh-pages：npm install gh-pages --save-dev
#   package.json 添加：
#     "homepage": "https://username.github.io/repo-name",
#     "predeploy": "npm run build",
#     "deploy": "gh-pages -d build"
 
# 部署到 Vercel（推荐）
npx vercel

环境变量管理

# .env（所有环境）
REACT_APP_API_URL=https://api.example.com
 
# .env.development（开发环境）
REACT_APP_DEBUG=true
 
# .env.production（生产环境）
REACT_APP_API_URL=https://api.production.com
 
# 在代码中使用
const apiUrl = process.env.REACT_APP_API_URL;

性能与安全

性能特点

  • 开发服务器启动速度：基于 Webpack 4，首次编译速度较慢（大型项目通常 30 秒以上），显著落后于 Vite（通常 1–3 秒）。
  • 热更新速度：使用 Webpack HMR，更新速度与项目规模正相关，大型项目中热更新可能需要 2–10 秒，Vite 的 ESM 原生 HMR 通常在 100 毫秒内完成。
  • 生产构建速度：Webpack 4 的生产构建通常需要 30–120 秒，Vite（Rollup）通常 10–30 秒。
  • 产物体积：默认配置下构建产物体积合理，但无法像现代工具那样精细控制代码分割粒度。
  • 运行时性能：与构建工具无关，取决于 React 代码本身。

已知安全问题

  • 依赖版本过时：[email protected] 内嵌 Webpack 4，而 Webpack 5 已于 2020 年发布；部分内嵌依赖（如 postcss、css-loader 等）版本滞后，可能存在已知漏洞。
  • immer 历史漏洞：CRA 曾依赖的 immer 版本存在原型污染漏洞（CVE），后续版本已修复，但部分旧项目仍受影响。
  • node-forge / nth-check / ansi-html 漏洞：react-scripts 传递依赖中存在多个历史 CVE 记录，需定期执行 npm audit 检查。
  • REACT_APP_ 前缀泄露风险：所有 REACT_APP_ 前缀变量会静态替换到前端代码中，若误将服务器端敏感信息以该前缀定义，会直接暴露在浏览器端。
  • Content Security Policy（CSP）问题：CRA 默认生成的 index.html 使用内联 &lt;script&gt; 标签注入运行时配置，与严格的 CSP 策略存在冲突，需手动调整或使用 INLINE_RUNTIME_CHUNK=false 环境变量规避。

技术对比

特性Create React AppVite（create-vite）Next.jsRsbuild
底层构建工具Webpack 4Vite（Rollup + esbuild）Webpack 5 / TurbopackRspack
维护状态已废弃（2025 年）活跃开发活跃开发活跃开发
开发服务器启动速度30–60 秒（慢）1–3 秒（极快）中等1–3 秒（极快）
热更新速度2–10 秒（慢）< 200ms（极快）中等（Turbopack 更快）< 200ms（极快）
生产构建速度30–120 秒10–30 秒中等10–30 秒
零配置✅ 是✅ 是✅ 是✅ 是
自定义配置能力有限（需 eject）强（vite.config.ts）强（next.config.js）强（rsbuild.config.ts）
SSR/SSG 支持❌ 不支持⚠️ 需插件✅ 内建⚠️ 需配合框架
TypeScript 支持基础（自动检测）完善完善完善
React 19 支持✅（最后维护版本）✅ 完整支持✅ 完整支持✅ 完整支持
路由方案需手动安装需手动安装✅ 内建文件系统路由需手动安装
PWA 支持✅ 内建⚠️ 需插件⚠️ 需配置⚠️ 需插件
React Server Components❌ 不支持❌ 不支持✅ 完整支持❌ 不支持
官方推荐度❌ 已废弃✅ 官方推荐✅ 官方推荐✅ 官方推荐

最佳实践

新项目建议

对于任何新项目，应直接使用现代替代方案：

# 方案1：使用 Vite（最轻量、最推荐）
npm create vite@latest my-app -- --template react-ts
 
# 方案2：使用 Next.js（需要 SSR/SSG/RSC）
npx create-next-app@latest my-app
 
# 方案3：使用 Rsbuild（Rspack 生态，极速构建）
npm create rsbuild@latest my-app
 
# 方案4：使用 React Router（纯 CSR + 路由框架）
# 参考 https://reactrouter.com/upgrading/component-routes

存量 CRA 项目迁移建议

迁移到 Vite（推荐，最简单）

# 1. 安装 Vite 及相关插件
npm install -D vite @vitejs/plugin-react
 
# 2. 创建 vite.config.ts
# import { defineConfig } from 'vite'
# import react from '@vitejs/plugin-react'
# export default defineConfig({
#   plugins: [react()],
# })
 
# 3. 修改 package.json scripts
# "dev": "vite",
# "build": "vite build",
# "preview": "vite preview"
 
# 4. 将 public/index.html 移到根目录 index.html
#    将 <script src="/src/index.js"> 改为 <script type="module" src="/src/index.jsx">
 
# 5. 移除 react-scripts
npm uninstall react-scripts
 
# 6. 处理环境变量：将 REACT_APP_ 前缀改为 VITE_
#    代码中 process.env.REACT_APP_XXX 改为 import.meta.env.VITE_XXX
 
# 7. 运行测试，修复问题

迁移到 Next.js（适合需要 SSR/RSC 的项目）

  • 参考 Next.js 官方迁移指南：From Create React App
  • 主要变化：文件系统路由替代 React Router、pages/ 或 app/ 目录结构、数据获取模式（Server Components / Route Handlers）

迁移前的评估清单

  • 是否执行过 eject？已 eject 的项目需先梳理自定义配置再迁移。
  • 是否依赖 CRA 特有的环境变量前缀（REACT_APP_）？需批量替换。
  • 是否使用了 setupProxy.js？需在 Vite 中使用 server.proxy 配置替代。
  • 是否依赖 PWA 功能？需使用 vite-plugin-pwa 替代。
  • 是否有 src/serviceWorker.js？需评估是否继续保留 PWA 能力。

代码迁移通用步骤

  1. 移除 react-scripts 依赖，安装新构建工具
  2. 处理环境变量前缀变更（REACT_APP_ → VITE_ / Next.js NEXT_PUBLIC_）
  3. 调整 index.html 入口文件位置
  4. 迁移自定义 Webpack 配置（如有）到新工具配置格式
  5. 更新 CI/CD 构建脚本
  6. 执行完整测试套件，修复不兼容问题
  7. 验证生产构建产物和部署流程

技术局限与边界

Webpack 4 过时

CRA 内嵌 Webpack 4，而 Webpack 5 已于 2020 年发布，带来持久缓存、模块联邦、更好的 Tree Shaking、原生 Web Workers 支持等重要特性。CRA 无法升级到 Webpack 5，因为 react-scripts 的封装层不允许此类重大变更。

无法灵活自定义配置

CRA 的零配置设计理念在简单项目中是优势，在复杂项目中是限制。任何超出预设范围的配置需求（如自定义 Loader、修改代码分割策略、配置 Module Federation、集成特殊资源处理）都必须执行 eject，或借助 craco、react-app-rewired 等第三方补丁工具，这些工具本身维护状况不佳，可能引入新的兼容性问题。

构建速度慢

Webpack 4 的整体架构决定了 CRA 在开发服务器启动、热更新、生产构建等环节的性能天花板。在大型项目（数千组件、数十万行代码）中，CRA 的开发体验显著落后于 Vite、Rsbuild 等基于 ESM 或 Rust 的新工具。

Content Security Policy（CSP）问题

CRA 默认在 index.html 中注入内联 &lt;script&gt; 标签用于运行时配置，与严格的 CSP 策略不兼容。虽然有 INLINE_RUNTIME_CHUNK=false 等环境变量可以规避，但这些 workaround 并非官方文档化方案，容易在版本升级中失效。

无 SSR/SSG/RSC 支持

CRA 仅支持客户端渲染（CSR），无法实现服务端渲染（SSR）、静态站点生成（SSG）或 React Server Components（RSC）。这些能力在现代 React 应用中日益重要，是选择 Next.js 等框架的核心原因。

依赖安全风险

react-scripts 封装了大量传递依赖，这些依赖的版本由 react-scripts 统一管理，开发者无法单独升级某个存在漏洞的传递依赖，只能等待 react-scripts 发布新版本（该版本已不太可能到来）。

学习资源

官方资源

迁移指南

社区讨论与分析

相关书籍与教程

2026 年现状

废弃状态确认

截至 2026 年 7 月，Create React App 已正式废弃超过 16 个月。React 团队在 2025 年 2 月 14 日的公告中明确表示：

"Create React App is deprecated." "CRA currently has no active maintainers." "We are publishing a new version to ensure compatibility with React 19, but we recommend moving to a framework."

官网 create-react-app.dev 首页已显示废弃横幅，GitHub 仓库 README.md 已更新废弃说明，npx create-react-app 命令执行时会输出废弃警告。

官方推荐替代方案

React 团队在废弃公告中明确推荐了以下替代方案：

框架（推荐大多数应用使用）

  • Next.js：最成熟的 React 全栈框架，支持 SSR/SSG/RSC/App Router，适合生产级应用
  • React Router：从路由库升级为完整框架，支持 CSR/SSR，最接近 CRA 的纯客户端渲染模式
  • Expo：React Native 应用的官方推荐框架

构建工具（适合自定义架构或学习用途）

  • Vite：最轻量、最快的前端构建工具，社区采用率最高，CRA 最直接的替代方案
  • Rsbuild：基于 Rspack（Rust）的极速构建工具，兼容 Webpack 生态
  • Parcel：零配置构建工具，自动检测项目类型

社区采用趋势

2026 年，新项目中使用 CRA 的比例已极低。根据多个前端开发者调查和技术趋势报告：

  • Vite 已成为 React 项目默认构建工具的首选，采用率超过 70%（新项目）
  • Next.js 在生产级 React 应用中占据主导地位，尤其是有 SEO 需求的项目
  • Rsbuild 作为新兴工具，在性能敏感型项目中快速增长
  • CRA 主要存在于 2023 年之前创建的存量项目中，其维护者面临逐步迁移的压力

存量项目维护建议

对于仍在使用 CRA 的项目：

  1. 无需立即迁移：CRA 在维护模式下仍然可用，已发布 React 19 兼容版本，短期内不会完全停止工作
  2. 定期运行 npm audit：检查传递依赖中的安全漏洞
  3. 制定迁移计划：在新功能开发放缓时，逐步迁移到 Vite 或 Next.js
  4. 避免新增 eject：已 eject 的项目迁移成本更高，应优先规划迁移路径
  5. 关注社区迁移工具：多个自动化迁移工具正在开发中，可降低迁移工作量

文档状态：本文档基于 2025 年 2 月 React 团队官方公告及 2026 年 7 月现状整理。Create React App 已正式废弃，新项目请勿使用。如需了解现代替代方案，请参阅 Vite 文档 或 Turbopack 文档。