Babel 安装与配置 #

安装 Babel #

核心包安装 #

Babel 的核心功能由 @babel/core 提供：

bash

# 使用 npm
npm install --save-dev @babel/core

# 使用 yarn
yarn add --dev @babel/core

# 使用 pnpm
pnpm add --save-dev @babel/core

CLI 工具安装 #

命令行工具用于在终端中使用 Babel：

bash

# 安装 CLI
npm install --save-dev @babel/cli

# 安装核心和 CLI
npm install --save-dev @babel/core @babel/cli

预设安装 #

预设包含一组常用插件：

bash

# 安装 env 预设（最常用）
npm install --save-dev @babel/preset-env

# 安装 React 预设
npm install --save-dev @babel/preset-react

# 安装 TypeScript 预设
npm install --save-dev @babel/preset-typescript

完整安装示例 #

bash

# 基础项目
npm install --save-dev @babel/core @babel/cli @babel/preset-env

# React 项目
npm install --save-dev @babel/core @babel/cli @babel/preset-env @babel/preset-react

# TypeScript 项目
npm install --save-dev @babel/core @babel/cli @babel/preset-env @babel/preset-typescript

# React + TypeScript 项目
npm install --save-dev @babel/core @babel/cli @babel/preset-env @babel/preset-react @babel/preset-typescript

包说明 #

核心包 #

包名	说明
`@babel/core`	Babel 核心编译引擎
`@babel/cli`	命令行工具
`@babel/parser`	JavaScript 解析器
`@babel/traverse`	AST 遍历工具
`@babel/generator`	代码生成器
`@babel/types`	AST 类型工具

预设包 #

包名	说明
`@babel/preset-env`	智能环境预设
`@babel/preset-react`	React JSX 支持
`@babel/preset-typescript`	TypeScript 支持
`@babel/preset-flow`	Flow 类型支持

运行时包 #

包名	说明
`@babel/runtime`	运行时辅助函数
`@babel/plugin-transform-runtime`	运行时插件
`core-js`	Polyfill 库
`regenerator-runtime`	async/await 支持

配置文件 #

配置文件类型 #

Babel 支持多种配置文件格式：

text

项目根目录/
├── babel.config.js      # 项目级配置（推荐）
├── babel.config.json    # JSON 格式配置
├── .babelrc.json        # JSON 格式配置
├── .babelrc             # 旧格式（仍支持）
└── package.json         # 内嵌配置

babel.config.js（推荐） #

使用 JavaScript 配置，灵活性最高：

javascript

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

  return {
    presets: [
      ['@babel/preset-env', {
        targets: {
          browsers: ['> 1%', 'last 2 versions', 'not dead']
        }
      }]
    ],
    plugins: []
  };
};

babel.config.json #

使用 JSON 格式，适合简单配置：

json

{
  "presets": [
    ["@babel/preset-env", {
      "targets": {
        "browsers": ["> 1%", "last 2 versions"]
      }
    }]
  ],
  "plugins": []
}

.babelrc.json #

适用于特定目录的配置：

json

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

package.json 内嵌配置 #

json

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

基本配置示例 #

最简配置 #

javascript

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

Web 项目配置 #

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-react'
    ],
    plugins: [
      isProduction && 'babel-plugin-transform-remove-console'
    ].filter(Boolean)
  };
};

Node.js 项目配置 #

javascript

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: {
        node: 'current'
      }
    }]
  ]
};

TypeScript 项目配置 #

javascript

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

React + TypeScript 配置 #

javascript

// babel.config.js
module.exports = {
  presets: [
    '@babel/preset-env',
    '@babel/preset-typescript',
    ['@babel/preset-react', { runtime: 'automatic' }]
  ]
};

配置选项详解 #

presets 配置 #

javascript

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

    // 数组形式（带选项）
    ['@babel/preset-env', {
      targets: { chrome: '80' },
      modules: false,
      useBuiltIns: 'usage',
      corejs: 3
    }]
  ]
};

plugins 配置 #

javascript

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

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

    // 内联插件
    function myCustomPlugin() {
      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'
      },

      // 组合
      targets: {
        browsers: ['> 1%', 'last 2 versions'],
        node: '12'
      }
    }]
  ]
};

modules 配置 #

javascript

module.exports = {
  presets: [
    ['@babel/preset-env', {
      // 保留 ES 模块
      modules: false,

      // 转换为 CommonJS
      modules: 'cjs',

      // 转换为 AMD
      modules: 'amd',

      // 转换为 UMD
      modules: 'umd',

      // 转换为 SystemJS
      modules: 'systemjs',

      // 自动检测
      modules: 'auto'
    }]
  ]
};

环境配置 #

多环境配置 #

javascript

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

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

  // 开发环境
  if (env === 'development') {
    config.sourceMaps = 'inline';
    config.plugins.push('@babel/plugin-transform-react-jsx-source');
  }

  // 生产环境
  if (env === 'production') {
    config.plugins.push('babel-plugin-transform-remove-console');
  }

  // 测试环境
  if (env === 'test') {
    config.presets.push(['@babel/preset-env', { targets: { node: 'current' } }]);
  }

  return config;
};

使用 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' } }]]
    }
  }
};

设置环境变量 #

bash

# 设置 BABEL_ENV
BABEL_ENV=production babel src --out-dir dist

# 设置 NODE_ENV
NODE_ENV=production babel src --out-dir dist

# package.json scripts
{
  "scripts": {
    "build": "BABEL_ENV=production babel src --out-dir dist",
    "dev": "BABEL_ENV=development babel src --out-dir dist --watch"
  }
}

Polyfill 配置 #

安装 Polyfill #

bash

# 安装 core-js
npm install core-js

# 安装 regenerator-runtime（async/await）
npm install regenerator-runtime

# 或安装完整 polyfill
npm install @babel/polyfill

useBuiltIns 配置 #

javascript

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      // 不自动引入 polyfill
      useBuiltIns: false,

      // 根据使用情况按需引入
      useBuiltIns: 'usage',
      corejs: 3,

      // 根据目标环境引入
      useBuiltIns: 'entry',
      corejs: 3
    }]
  ]
};

usage 模式 #

javascript

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

// 源代码
const arr = [1, 2, 3].includes(2);
const promise = Promise.resolve();

// 编译后（自动注入需要的 polyfill）
import "core-js/modules/es.array.includes.js";
import "core-js/modules/es.promise.js";
var arr = [1, 2, 3].includes(2);
var promise = Promise.resolve();

entry 模式 #

javascript

// 配置
module.exports = {
  presets: [
    ['@babel/preset-env', {
      useBuiltIns: 'entry',
      corejs: 3
    }]
  ]
};

// 入口文件
import 'core-js/stable';
import 'regenerator-runtime/runtime';

// Babel 会根据目标环境替换为具体的 polyfill

Source Map 配置 #

javascript

// babel.config.js
module.exports = {
  presets: ['@babel/preset-env'],
  sourceMaps: true,        // 生成外部 .map 文件
  sourceMaps: 'inline',    // 内联 source map
  sourceMaps: 'both'       // 两种都生成
};

忽略文件配置 #

忽略特定文件 #

javascript

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

仅编译特定文件 #

javascript

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

extends 配置 #

继承其他配置文件：

javascript

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

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']
    }
  ]
};

缓存配置 #

javascript

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

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

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

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

实战配置模板 #

Web 应用模板 #

javascript

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

  return {
    presets: [
      ['@babel/preset-env', {
        targets: '> 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',
      isDevelopment && '@babel/plugin-transform-react-jsx-source',
      isProduction && 'babel-plugin-transform-remove-console'
    ].filter(Boolean)
  };
};

库开发模板 #

javascript

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

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']
    }
  ]
};

验证配置 #

检查配置 #

bash

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

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

测试配置 #

bash

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

# 带详细输出
npx babel src --out-dir dist --verbose

常见问题 #

问题一：找不到预设 #

bash

Error: Cannot find module '@babel/preset-env'

解决方案：

bash

npm install --save-dev @babel/preset-env

问题二：配置不生效 #

bash

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

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

问题三：Polyfill 重复 #

javascript

// 避免在多个入口重复引入
// 使用 useBuiltIns: 'usage' 自动处理

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

下一步 #

现在你已经掌握了 Babel 的安装和配置，接下来学习基础使用开始实际编译代码！