从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被淘汰的完整技术探索过程，希望对遇到类似问题的开发者有帮助。