从Docker构建失败到CRA被淘汰：一个React项目的ES模块探索记录

开头

最近给一个React项目配Docker构建，碰到了一个看起来简单实际很麻烦的错误：

Failed to compile.
The target environment doesn't support dynamic import() syntax so it's not possible to use external type 'module' within a script
Did you mean to build a EcmaScript Module ('output.module: true')?

这个错误让我深入了解了Create React App (CRA)、ES模块、Webpack和CRACO之间的关系。最后还发现了一个消息：CRA已经被官方宣布逐步淘汰了。

问题是怎么来的

一开始的错误

项目用的是Create React App构建，在Docker环境里构建失败了。错误信息说动态导入语法不被支持。

项目环境

• React版本: 18.2.0
• CRA版本: react-scripts 5.0.1
• 构建工具: Docker + npm run build
• 出问题的代码: src/reportWebVitals.js 里的动态导入

我是怎么分析问题的

1. 先找到问题在哪

发现 reportWebVitals.js 里用了动态导入：

// 原来的代码（有问题）
const reportWebVitals = onPerfEntry => {if (onPerfEntry && onPerfEntry instanceof Function) {import('web-vitals').then(({ getCLS, getFID, getFCP, getLCP, getTTFB }) => {// 用这些函数});}
};

2. 试了简单修复

一开始想把动态导入改成静态导入：

// 修好的代码
import { getCLS, getFID, getFCP, getLCP, getTTFB } from 'web-vitals';const reportWebVitals = onPerfEntry => {if (onPerfEntry && onPerfEntry instanceof Function) {getCLS(onPerfEntry);getFID(onPerfEntry);getFCP(onPerfEntry);getLCP(onPerfEntry);getTTFB(onPerfEntry);}
};

但问题还在，说明不是这个文件的问题。

3. 深入调查

继续查发现：

• 项目里确实没别的动态导入
• 问题可能来自依赖包或者webpack配置
• 需要开启ES模块输出支持

解决方案：用CRACO

CRACO是什么？

CRACO (Create React App Configuration Override) 是个工具，让你能覆盖CRA的webpack配置，不用执行 npm run eject。

怎么装和配置

# 装CRACO
npm install --save-dev @craco/craco

创建 craco.config.js：

module.exports = {webpack: {configure: (webpackConfig) => {// 关键配置：开启ES模块输出webpackConfig.output = {...webpackConfig.output,module: true,              // 开启模块输出libraryTarget: 'module',   // 设置库目标是模块};// 加webpack实验性功能webpackConfig.experiments = {...webpackConfig.experiments,outputModule: true,        // 开启模块输出实验};// 配置模块解析回退webpackConfig.resolve = {...webpackConfig.resolve,fallback: {...webpackConfig.resolve?.fallback,"fs": false,"path": false,"crypto": false,}};return webpackConfig;},},
};

改 package.json 脚本：

{"scripts": {"start": "env-cmd -f .env craco start","build": "env-cmd -f .env craco build","test": "craco test"}
}

验证方案

试着去掉CRACO看看是不是真的需要：

1. 备份配置
2. 去掉CRACO
3. 测试构建
4. 结果：构建失败

结论：CRACO确实是必需的。

技术原理

Webpack、ES模块和CRACO的关系

React项目↓
Create React App (CRA)↓
react-scripts (内置webpack配置)↓
Webpack (模块打包器)↓
处理模块 (CommonJS/ES模块/动态导入)↓
输出打包文件需要自定义时：↓
CRACO (配置覆盖层)↓
修改Webpack配置↓
支持更多模块特性

ES模块 vs CommonJS

// ES模块 (ES6+)
export const value = 42;
import { value } from './module.js';// CommonJS (Node.js)
module.exports = { value: 42 };
const { value } = require('./module.js');

为什么CRA默认不支持ES模块输出？

1. 兼容性考虑：要支持老浏览器
2. 生态系统兼容性：很多npm包还是CommonJS格式
3. 构建复杂度：ES模块输出需要更多配置
4. 稳定性优先：CRA追求"零配置"，避免复杂配置

重大发现：CRA被淘汰了

官方说法

2025年2月14日，React官方宣布逐步淘汰Create React App！

这意味着：

• CRA不再更新
• 最新版本停在 react-scripts 5.0.1
• 不再支持新特性，包括ES模块输出
• 官方建议迁移到其他现代构建工具

版本对比

// CRA 4.x (2020-2021)
❌ 不支持ES模块输出
❌ 不支持动态导入// CRA 5.x (2022) - 现在最新的
❌ 还是不支持ES模块输出
⚠️ 需要CRACO才能支持// CRA 6.x (没发布)
❌ 被官方取消了
❌ 不会有新版本

现代替代方案

1. Vite - 推荐方案

// vite.config.js
export default {build: {// ✅ 默认支持ES模块输出target: 'esnext',rollupOptions: {output: {format: 'es' // ES模块格式}}}
}

好处：

• 原生ES模块支持
• 构建更快
• 开发体验现代化
• 社区活跃

2. Next.js

// next.config.js
module.exports = {experimental: {// ✅ 支持ES模块esmExternals: true}
}

3. Parcel

// Parcel 默认支持ES模块
// ✅ 零配置ES模块支持
// ✅ 开箱即用

项目建议

短期方案（继续用CRA + CRACO）

// 现在这个方案还能用
✅ 用 react-scripts 5.0.1 + CRACO
✅ 通过CRACO配置ES模块支持
✅ 项目能正常运行// 但要注意
⚠️ CRA不再维护，安全更新可能停
⚠️ 依赖包可能过时
⚠️ 长期维护有风险

长期方案（迁移到现代工具）

迁移优先级：

1. Vite - 最接近CRA的体验，迁移成本最低
2. Next.js - 如果需要服务端渲染
3. Parcel - 如果喜欢零配置

最终解决方案

Dockerfile修复

顺便修了Dockerfile里的一些问题：

# 修之前
RUN apt-get update && apt-get install -y --no-install-recommends
EXPOSE 3000# 修之后
RUN apt-get update && apt-get install -y --no-install-recommends \curl \&& rm -rf /var/lib/apt/lists/*
EXPOSE 3003  # 匹配.env里的PORT配置

构建结果

# 最终构建成功
✅ 本地构建：npm run build
✅ Docker构建：docker build -t ts-mvp-frontend:latest
✅ 动态导入问题解决
✅ ES模块支持开启

经验总结

学到的东西

1. 问题往往比表面复杂：看起来简单的动态导入问题，背后涉及整个模块系统
2. 工具链很重要：现代JavaScript开发需要理解整个工具链
3. 技术选型的影响：CRA的设计理念虽然简化了配置，但也限制了灵活性
4. 技术生态变化很快：CRA的淘汰提醒我们技术栈需要持续更新

最佳实践

1. 深入理解工具：不要只停留在表面使用
2. 关注官方动态：及时了解技术栈的变化
3. 准备迁移计划：对于被淘汰的技术要有应急预案
4. 记录文档：记录解决过程，方便团队分享

结尾

这次探索让我深刻理解了现代JavaScript开发中模块系统的重要性，以及工具链配置的复杂性。CRA的逐步淘汰也提醒我们，在技术快速发展的今天，保持技术栈的现代化和可维护性至关重要。

对于正在用CRA的项目，建议：

• 短期：继续用CRA + CRACO的方案
• 中期：制定迁移计划
• 长期：迁移到Vite等现代工具

技术总是在不断演进，作为开发者，我们需要保持学习的心态，拥抱变化，选择最适合项目的技术栈。

---

这篇文章记录了一个Docker构建错误到发现CRA被淘汰的完整技术探索过程，希望对遇到类似问题的开发者有帮助。