在Create React App项目中启用实验性装饰器语法

本文旨在解决在Create React App (CRA) 项目中使用实验性装饰器语法时遇到的`Support for the experimental syntax 'decorators' isn't currently enabled`错误。通过引入`customize-cra`工具，我们将详细指导如何配置Babel，以正确解析和转换装饰器语法，从而在不弹出（eject）CRA配置的情况下，顺利集成如WatermelonDB等依赖装饰器的库。

理解装饰器语法错误

在现代JavaScript和TypeScript开发中，装饰器（Decorators）是一种强大的元编程特性，允许我们以声明式的方式修改类、方法、属性或参数。例如，在使用像@nozbe/watermelondb这样的库时，你可能会看到如下代码：

import { Model } from '@nozbe/watermelondb';
import { field } from '@nozbe/watermelondb/decorators';

export default class Staff extends Model {
  static table = 'staff';

  @field('name') name; // 这里使用了装饰器
}

当你尝试运行包含此类代码的React应用程序时，如果Babel没有正确配置以支持装饰器语法，你可能会遇到以下编译错误：

ERROR in ./src/watermelon/model/Staff.js
Module build failed (from ./node_modules/babel-loader/lib/index.js):
SyntaxError: C:\projects\siloc-react-laravel\siloc-react\src\watermelon\model\Staff.js: Support for the experimental syntax 'decorators' isn't currently enabled (8:3):

   6 |
   7 |
>  8 |   @field('name') name;
     |   ^
   9 |   // @action async getStaff()
  10 |   // {
  11 |   //   return {

Add @babel/plugin-proposal-decorators (https://github.com/babel/babel/tree/main/packages/babel-plugin-proposal-decorators) to the 'plugins' section of your Babel config to enable transformation.

这个错误明确指出，Babel构建工具链缺少对实验性装饰器语法的支持，并建议添加@babel/plugin-proposal-decorators插件。

Create React App (CRA) 中的Babel配置挑战

对于传统的Babel项目，解决这个问题通常是在项目根目录下的.babelrc文件或package.json的babel字段中添加相应的插件。然而，Create React App项目默认隐藏了其Webpack和Babel配置，由react-scripts包进行管理。这意味着直接修改package.json中的babel字段或创建.babelrc文件，可能不会被react-scripts识别或采纳，导致即使配置了插件，错误依然存在。

为了在不“弹出”（eject）CRA配置的前提下，定制Babel配置，我们需要借助像customize-cra这样的工具。customize-cra允许我们通过一个简单的配置文件来覆盖CRA的内部配置。

解决方案：使用 customize-cra 启用装饰器

以下是解决此问题的详细步骤：

步骤一：安装必要的依赖

首先，确保你的项目已经安装了react-app-rewired和customize-cra。react-app-rewired用于替代react-scripts来启动、构建和测试应用，而customize-cra则提供了一系列辅助函数来修改配置。同时，我们需要安装Babel装饰器插件。

npm install --save-dev customize-cra react-app-rewired @babel/plugin-proposal-decorators @babel/plugin-proposal-class-properties @babel/plugin-transform-runtime
# 或者使用 yarn
yarn add --dev customize-cra react-app-rewired @babel/plugin-proposal-decorators @babel/plugin-proposal-class-properties @babel/plugin-transform-runtime

注意：@babel/plugin-proposal-class-properties 和 @babel/plugin-transform-runtime 通常也是CRA项目中常用的Babel插件，如果你的项目在package.json的babel字段中已经定义了这些插件，建议一并迁移到config-overrides.js中。

千图设计室AI海报

千图网旗下的智能海报在线设计平台

下载

步骤二：修改 package.json 脚本

将package.json中scripts字段下的start, build, test命令从react-scripts改为react-app-rewired。

{
  "name": "your-app-name",
  "version": "0.1.0",
  // ... 其他配置
  "scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
    "eject": "react-scripts eject"
  },
  // ... 其他配置
}

步骤三：创建 config-overrides.js 文件

在项目根目录（与package.json同级）创建一个名为config-overrides.js的文件，并添加以下内容：

const { addBabelPlugins, override } = require("customize-cra");

module.exports = override(
  ...addBabelPlugins(
    [
      "@babel/plugin-proposal-decorators",
      {
        "legacy": true // 使用 legacy 模式以兼容旧版装饰器规范
      }
    ],
    // 如果你的项目还使用了其他Babel插件，例如类属性，也应在此处添加
    [
      "@babel/plugin-proposal-class-properties",
      {
        "loose": true // 使用 loose 模式以获得更好的兼容性或性能
      }
    ],
    // 运行时转换插件，通常也需要
    [
      "@babel/plugin-transform-runtime",
      {
        "helpers": true,
        "regenerator": true
      }
    ]
  )
);

legacy: true 的说明：@babel/plugin-proposal-decorators插件支持两种模式：legacy（旧版）和非legacy（最新版）。legacy: true通常用于兼容较早的装饰器提案规范，这在许多现有项目和库（如WatermelonDB）中是常见的做法。如果你的项目遇到与装饰器相关的进一步问题，可以尝试切换此选项。

loose: true 的说明：@babel/plugin-proposal-class-properties插件的loose: true选项会使Babel以更宽松的方式转换类属性，通常会生成更简洁的代码，并可能与某些旧版浏览器或运行时环境有更好的兼容性。

步骤四：移除 package.json 中的Babel配置（可选但推荐）

如果你的package.json中存在一个独立的babel字段，其中包含了之前尝试配置的Babel插件，建议将其删除。这样做可以避免潜在的配置冲突或冗余，因为现在所有Babel配置都将通过config-overrides.js进行管理。

{
  // ...
  "babel": { // 移除此整个 babel 字段
    "presets": [
      "@babel/preset-react"
    ],
    "plugins": [
      [
        "@babel/plugin-proposal-decorators",
        {
          "legacy": true
        }
      ],
      [
        "@babel/plugin-proposal-class-properties",
        {
          "loose": true
        }
      ],
      [
        "@babel/plugin-transform-runtime",
        {
          "helpers": true,
          "regenerator": true
        }
      ]
    ]
  },
  // ...
}

验证与运行

完成上述步骤后，重新启动你的开发服务器：

npm start
# 或者
yarn start

此时，Babel应该能够正确解析并转换装饰器语法，你的应用程序将不再报错，可以正常运行。

注意事项与总结

• 插件顺序： 在addBabelPlugins中，插件的顺序通常很重要。@babel/plugin-proposal-decorators应放在其他可能依赖于装饰器转换的插件之前。
• 版本兼容性： 确保你安装的Babel插件版本与你的Babel核心版本兼容。通常，npm install会帮你处理好依赖关系。
• 官方文档： customize-cra和Babel插件的官方文档是获取最新信息和高级配置的最佳来源。
• 不弹出（Eject）的优势： 使用customize-cra的优势在于，你可以在不弹出CRA配置的情况下，灵活地修改其底层配置。这样，你仍然可以享受CRA带来的升级便利，而无需手动维护复杂的Webpack和Babel配置。

通过遵循本教程，你将能够轻松地在Create React App项目中启用实验性装饰器语法，从而利用其强大的特性来构建更优雅、更可维护的代码。