#output.autoExternal

• 类型：

type AutoExternal =
  | boolean
  | {
      dependencies?: boolean;
      optionalDependencies?: boolean;
      devDependencies?: boolean;
      peerDependencies?: boolean;
    };

• 默认值： false

用于自动 external 根目录 package.json 中声明的依赖。开启后，Rsbuild 会读取 <root>/package.json 中的依赖字段，并将匹配到的包名转换为 output.externals 规则。

这个能力适用于 Node.js 或 SSR bundle 场景。例如，一些依赖需要由运行时加载，而不是被打进 bundle，包括观测 SDK、原生插件，或依赖运行时 instrumentation 的包。

#默认行为

当 output.autoExternal 为 true 时，以下依赖类型默认会被 external：

• dependencies
• optionalDependencies
• peerDependencies

以下依赖类型默认不会被 external：

• devDependencies

它等价于如下配置：

export default {
  output: {
    autoExternal: {
      dependencies: true,
      optionalDependencies: true,
      peerDependencies: true,
      devDependencies: false,
    },
  },
};

#子路径导入

Rsbuild 也会 external 匹配依赖的子路径导入。例如，如果 react 声明在 dependencies 中，下面两个导入都会被 external：

import React from 'react';
import { jsx } from 'react/jsx-runtime';

#示例

#开启自动 external

export default {
  output: {
    target: 'node',
    autoExternal: true,
  },
};

#自定义依赖类型

export default {
  output: {
    target: 'node',
    autoExternal: {
      dependencies: true,
      optionalDependencies: true,
      peerDependencies: true,
      devDependencies: true,
    },
  },
};

#关闭某类依赖

export default {
  output: {
    target: 'node',
    autoExternal: {
      peerDependencies: false,
    },
  },
};

#与 output.externals 的关系

output.externals 的优先级高于 output.autoExternal。你可以通过 output.externals 手动定制特定包的 external 格式，再通过 output.autoExternal 自动处理 package.json 中剩余的依赖。

export default {
  output: {
    target: 'node',
    externals: {
      react: 'react-18',
    },
    autoExternal: true,
  },
};

在上面的例子中，react 会遵循手动配置的 output.externals，不会使用自动生成的 external 规则。

当 output.externals 使用对象形式配置时，Rsbuild 会跳过对象 key 中对应包名的自动 external 规则。例如，如果你在 output.externals 中配置了 react，Rsbuild 不会再为 react 或其子路径导入（如 react/jsx-runtime）生成自动 external 规则。如果你希望这些子路径导入仍然保持 external，也需要将它们添加到 output.externals 中。

对于数组、函数或正则表达式等更复杂的 output.externals 配置，Rsbuild 会将它们与 output.autoExternal 生成的规则合并。如果最终行为不符合预期，可以使用 DEBUG=rsbuild 或 rsbuild inspect 查看实际生效的 externals 配置。