Babel 配置 #

配置文件类型 #

Babel 支持多种配置文件格式，每种都有其适用场景：

text

项目根目录/
├── babel.config.js      # 项目级配置（推荐）
├── babel.config.json    # JSON 格式配置
├── babel.config.cjs     # CommonJS 格式
├── babel.config.mjs     # ES 模块格式
├── .babelrc.json        # 相对路径配置
├── .babelrc             # 旧格式（仍支持）
└── package.json         # 内嵌配置

babel.config.js（推荐） #

javascript

// babel.config.js
module.exports = function(api) {
  api.cache(true);

  return {
    presets: ['@babel/preset-env'],
    plugins: []
  };
};

babel.config.json #

json

{
  "presets": ["@babel/preset-env"],
  "plugins": []
}

babel.config.mjs #

javascript

// babel.config.mjs
export default {
  presets: ['@babel/preset-env'],
  plugins: []
};

.babelrc.json #

json

{
  "presets": ["@babel/preset-env"],
  "plugins": []
}

package.json 内嵌 #

json

{
  "name": "my-project",
  "babel": {
    "presets": ["@babel/preset-env"],
    "plugins": []
  }
}

配置文件选择 #

项目级配置 vs 相对路径配置 #

text

┌─────────────────────────────────────────────────────────────┐
│                    配置文件作用范围                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  babel.config.js（项目级）                                   │
│  ├── 作用于整个项目                                          │
│  ├── 适合 monorepo                                          │
│  └── 推荐用于大多数项目                                      │
│                                                              │
│  .babelrc.json（相对路径）                                   │
│  ├── 只作用于当前目录及子目录                                │
│  ├── 适合特定目录的配置                                      │
│  └── 可以被 babel.config.js 覆盖                             │
│                                                              │
└─────────────────────────────────────────────────────────────┘

配置文件查找顺序 #

text

1. 查找 babel.config.js
2. 查找 babel.config.json
3. 查找 babel.config.cjs
4. 查找 babel.config.mjs
5. 查找 .babelrc.json / .babelrc
6. 查找 package.json 中的 babel 字段

配置选项详解 #

presets #

javascript

module.exports = {
  presets: [
    // 字符串形式
    '@babel/preset-env',

    // 数组形式（带选项）
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      modules: false
    }],

    // 带条件的预设
    process.env.NODE_ENV === 'test' && '@babel/preset-env'
  ].filter(Boolean)
};

plugins #

javascript

module.exports = {
  plugins: [
    // 字符串形式
    '@babel/plugin-transform-runtime',

    // 数组形式（带选项）
    ['@babel/plugin-proposal-decorators', { legacy: true }],

    // 内联插件
    function customPlugin() {
      return {
        visitor: {}
      };
    }
  ]
};

targets #

javascript

module.exports = {
  presets: [
    ['@babel/preset-env', {
      // 字符串形式
      targets: '> 0.25%, not dead',

      // 对象形式
      targets: {
        chrome: '80',
        firefox: '78',
        safari: '14',
        edge: '88'
      },

      // Node.js
      targets: {
        node: 'current'
      },

      // ES 模块支持
      targets: {
        esmodules: true
      }
    }]
  ]
};

modules #

javascript

module.exports = {
  presets: [
    ['@babel/preset-env', {
      modules: false,    // 保留 ES 模块
      modules: 'cjs',    // CommonJS
      modules: 'amd',    // AMD
      modules: 'umd',    // UMD
      modules: 'systemjs', // SystemJS
      modules: 'auto'    // 自动检测
    }]
  ]
};

useBuiltIns 和 corejs #

javascript

module.exports = {
  presets: [
    ['@babel/preset-env', {
      useBuiltIns: 'usage',
      corejs: {
        version: 3,
        proposals: true
      }
    }]
  ]
};

sourceMaps #

javascript

module.exports = {
  sourceMaps: true,       // 生成外部 .map 文件
  sourceMaps: 'inline',   // 内联 source map
  sourceMaps: 'both',     // 两种都生成
  sourceMaps: false       // 不生成
};

sourceType #

javascript

module.exports = {
  sourceType: 'module',     // ES 模块
  sourceType: 'script',     // 脚本
  sourceType: 'unambiguous' // 自动检测
};

assumptions #

javascript

module.exports = {
  assumptions: {
    arrayLikeIsIterable: true,
    constantReexports: true,
    enumerableModuleMeta: true,
    iterableIsArray: true,
    mutableTemplateObject: true,
    noClassCalls: true,
    noDocumentAll: true,
    noIncompleteNsImportDetection: true,
    noNewArrows: true,
    objectRestNoSymbols: true,
    privateFieldsAsProperties: true,
    pureGetters: true,
    setComputedProperties: true,
    setPublicClassFields: true,
    setSpreadProperties: true,
    skipForOfIteratorClosing: true,
    superIsCallableConstructor: true
  }
};

环境配置 #

env 配置 #

javascript

// babel.config.js
module.exports = {
  presets: ['@babel/preset-env'],
  env: {
    development: {
      sourceMaps: 'inline',
      plugins: [
        '@babel/plugin-transform-react-jsx-source'
      ]
    },
    production: {
      plugins: [
        'babel-plugin-transform-remove-console',
        'babel-plugin-transform-react-remove-prop-types'
      ]
    },
    test: {
      presets: [
        ['@babel/preset-env', { targets: { node: 'current' } }]
      ]
    }
  }
};

使用函数配置 #

javascript

// babel.config.js
module.exports = function(api) {
  const env = api.env();
  const isProduction = env === 'production';
  const isDevelopment = env === 'development';
  const isTest = env === 'test';

  return {
    presets: [
      ['@babel/preset-env', {
        targets: isTest ? { node: 'current' } : '> 0.25%, not dead',
        modules: isTest ? 'commonjs' : false
      }]
    ],
    plugins: [
      '@babel/plugin-transform-runtime',
      isDevelopment && '@babel/plugin-transform-react-jsx-source',
      isProduction && 'babel-plugin-transform-remove-console'
    ].filter(Boolean),
    sourceMaps: isDevelopment ? 'inline' : true
  };
};

环境变量设置 #

bash

# 设置 BABEL_ENV
BABEL_ENV=production babel src -d dist

# 设置 NODE_ENV
NODE_ENV=production babel src -d dist

# package.json scripts
{
  "scripts": {
    "build": "BABEL_ENV=production babel src -d dist",
    "dev": "BABEL_ENV=development babel src -d dist -w",
    "test": "BABEL_ENV=test jest"
  }
}

overrides 配置 #

overrides 允许对不同文件应用不同配置：

javascript

// babel.config.js
module.exports = {
  presets: ['@babel/preset-env'],
  overrides: [
    {
      test: './src/legacy/**',
      presets: [
        ['@babel/preset-env', { targets: { ie: '11' } }]
      ]
    },
    {
      test: ['./src/modern/**', './src/new/**'],
      presets: [
        ['@babel/preset-env', { targets: { esmodules: true } }]
      ]
    },
    {
      test: '**/*.ts',
      presets: ['@babel/preset-typescript']
    },
    {
      test: '**/*.tsx',
      presets: [
        '@babel/preset-typescript',
        '@babel/preset-react'
      ]
    }
  ]
};

Monorepo 配置 #

javascript

// babel.config.js
module.exports = {
  presets: ['@babel/preset-env'],
  overrides: [
    {
      test: './packages/react-app/**',
      presets: ['@babel/preset-react']
    },
    {
      test: './packages/node-server/**',
      presets: [
        ['@babel/preset-env', { targets: { node: 'current' } }]
      ]
    },
    {
      test: './packages/shared/**',
      presets: ['@babel/preset-typescript']
    }
  ]
};

缓存配置 #

API 缓存 #

javascript

// babel.config.js
module.exports = function(api) {
  // 始终缓存
  api.cache(true);

  // 永不缓存
  api.cache(false);

  // 根据环境变量缓存
  api.cache.using(() => process.env.NODE_ENV);

  // 根据多个条件缓存
  api.cache.using(() => {
    return process.env.NODE_ENV + process.env.BABEL_ENV;
  });

  // 根据文件变化缓存
  api.cache.invalidate(() => {
    return api.caller(caller => caller && caller.name);
  });

  return {
    presets: ['@babel/preset-env']
  };
};

缓存目录 #

bash

# 默认缓存目录
node_modules/.cache/babel-loader/

# 自定义缓存目录
BABEL_CACHE_PATH=/tmp/babel-cache babel src -d dist

ignore 和 only #

ignore 配置 #

javascript

// babel.config.js
module.exports = {
  presets: ['@babel/preset-env'],
  ignore: [
    './node_modules',
    './dist',
    '**/*.test.js',
    '**/__tests__/**',
    '**/__mocks__/**'
  ]
};

only 配置 #

javascript

// babel.config.js
module.exports = {
  presets: ['@babel/preset-env'],
  only: [
    './src',
    './lib',
    '**/*.js'
  ]
};

函数形式 #

javascript

module.exports = {
  ignore: [
    function(filepath) {
      return filepath.includes('node_modules');
    }
  ]
};

extends 配置 #

继承其他配置文件：

javascript

// babel.config.js
module.exports = {
  extends: './babel.base.config.js',
  presets: [
    // 追加配置
  ],
  plugins: [
    // 追加配置
  ]
};

共享配置 #

javascript

// @scope/babel-preset-shared/index.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      useBuiltIns: 'usage',
      corejs: 3
    }]
  ],
  plugins: [
    '@babel/plugin-transform-runtime'
  ]
};

// 项目中使用
// babel.config.js
module.exports = {
  extends: '@scope/babel-preset-shared',
  plugins: [
    // 项目特定插件
  ]
};

caller 配置 #

caller 用于传递调用者信息：

javascript

// 调用 Babel 时传递 caller
babel.transformSync(code, {
  presets: ['@babel/preset-env'],
  caller: {
    name: 'my-tool',
    supportsStaticESM: true,
    supportsDynamicImport: true,
    supportsTopLevelAwait: true
  }
});

// babel.config.js 中使用
module.exports = function(api) {
  const supportsESM = api.caller(caller => caller?.supportsStaticESM);

  return {
    presets: [
      ['@babel/preset-env', {
        modules: supportsESM ? false : 'auto'
      }]
    ]
  };
};

测试配置 #

Jest 配置 #

javascript

// babel.config.js
module.exports = function(api) {
  const isTest = api.env('test');

  return {
    presets: [
      ['@babel/preset-env', {
        targets: isTest ? { node: 'current' } : '> 0.25%, not dead',
        modules: isTest ? 'commonjs' : false
      }]
    ]
  };
};

// jest.config.js
module.exports = {
  transform: {
    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest'
  }
};

完整配置示例 #

Web 应用 #

javascript

// babel.config.js
module.exports = function(api) {
  const env = api.env();
  const isProduction = env === 'production';
  const isDevelopment = env === 'development';
  const isTest = env === 'test';

  return {
    presets: [
      ['@babel/preset-env', {
        targets: isTest ? { node: 'current' } : '> 0.25%, not dead',
        useBuiltIns: 'usage',
        corejs: { version: 3, proposals: true },
        modules: isTest ? 'commonjs' : false
      }],
      ['@babel/preset-react', { runtime: 'automatic' }]
    ],
    plugins: [
      ['@babel/plugin-transform-runtime', {
        corejs: false,
        helpers: true,
        regenerator: true
      }],
      isDevelopment && '@babel/plugin-transform-react-jsx-source',
      isProduction && 'babel-plugin-transform-remove-console'
    ].filter(Boolean),
    sourceMaps: isDevelopment ? 'inline' : true,
    assumptions: {
      setPublicClassFields: true
    }
  };
};

库开发 #

javascript

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: { node: '12' },
      modules: false
    }]
  ],
  plugins: [
    ['@babel/plugin-transform-runtime', {
      useESModules: true
    }]
  ],
  assumptions: {
    constantReexports: true,
    enumerableModuleMeta: true
  }
};

Monorepo #

javascript

// babel.config.js
module.exports = function(api) {
  const env = api.env();

  return {
    presets: [
      ['@babel/preset-env', {
        targets: '> 0.25%, not dead',
        modules: false
      }]
    ],
    overrides: [
      {
        test: './packages/client/**',
        presets: [
          ['@babel/preset-env', { targets: '> 0.5%, not dead' }],
          ['@babel/preset-react', { runtime: 'automatic' }]
        ]
      },
      {
        test: './packages/server/**',
        presets: [
          ['@babel/preset-env', { targets: { node: 'current' } }]
        ]
      },
      {
        test: './packages/shared/**',
        presets: ['@babel/preset-typescript']
      }
    ]
  };
};

TypeScript + React #

javascript

// babel.config.js
module.exports = function(api) {
  const isProduction = api.env('production');

  return {
    presets: [
      ['@babel/preset-env', {
        targets: '> 0.25%, not dead',
        useBuiltIns: 'usage',
        corejs: 3
      }],
      '@babel/preset-typescript',
      ['@babel/preset-react', { runtime: 'automatic' }]
    ],
    plugins: [
      ['@babel/plugin-proposal-decorators', { legacy: true }],
      ['@babel/plugin-proposal-class-properties', { loose: true }],
      '@babel/plugin-transform-runtime',
      isProduction && 'babel-plugin-transform-remove-console'
    ].filter(Boolean)
  };
};

配置调试 #

显示配置 #

bash

# 显示当前配置
npx babel --show-config

# 显示特定环境的配置
BABEL_ENV=production npx babel --show-config

# 显示特定文件的配置
npx babel --show-config src/index.js

验证配置 #

bash

# 编译测试
npx babel src --out-dir dist --verbose

# 检查配置文件
npx babel --help

常见问题 #

问题一：配置不生效 #

javascript

// 检查配置文件位置
// babel.config.js 应该在项目根目录

// 检查配置文件名称
// 确保是 babel.config.js 而不是 babel.config.js.txt

// 检查配置语法
// 使用 --show-config 验证

问题二：环境变量不生效 #

bash

# 确保环境变量已设置
echo $BABEL_ENV

# 在 package.json scripts 中设置
{
  "scripts": {
    "build": "BABEL_ENV=production babel src -d dist"
  }
}

问题三：overrides 不生效 #

javascript

// 确保 test 路径正确
module.exports = {
  overrides: [
    {
      // 使用正确的路径格式
      test: './src/legacy/**',  // 正确
      // test: 'src/legacy',    // 可能不正确
    }
  ]
};

下一步 #

现在你已经掌握了 Babel 的完整配置，接下来学习高级特性了解更多高级用法！