treeshake

• 类型：boolean | TreeshakingOptions

  ¥Type: boolean | TreeshakingOptions

• 默认值：true

  ¥Default: true

控制 tree-shaking（死代码消除）。当 true 设置为 true 时，会从 bundle 中删除未使用的代码，以减小 bundle 的大小。

¥Controls tree-shaking (dead code elimination). When true, unused code will be removed from the bundle to reduce bundle size.

TreeshakingOptions

传递对象时，你可以使用以下选项微调摇树行为：

¥When passing an object, you can fine-tune the tree-shaking behavior with the following options:

treeshake.moduleSideEffects

• 类型：boolean | readonly string[] | ModuleSideEffectsRule[] | ((id: string, external: boolean) => boolean | undefined) | 'no-external'

  ¥Type: boolean | readonly string[] | ModuleSideEffectsRule[] | ((id: string, external: boolean) => boolean | undefined) | 'no-external'

• 默认值：true

  ¥Default: true

控制导入的模块是否有副作用。此选项有助于 tree-shaking 确定哪些模块即使导出未被使用也必须包含，以及哪些模块可以安全删除。

¥Controls whether imported modules have side effects. This option helps tree-shaking determine which modules must be included even if their exports aren't used, and which can be safely removed.

价值观：

¥Values:

• true：所有模块都假定具有副作用，即使未使用其导出的任何内容，也将包含在打包文件中。

  ¥true: All modules are assumed to have side effects and will be included in the bundle even if none of their exports are used.

• false：所有模块均无副作用。这会启用积极的 tree-shaking，删除任何未使用导出的模块。

  ¥false: No modules have side effects. This enables aggressive tree-shaking, removing any modules whose exports are not used.

• string[]：具有副作用的模块 ID 数组。只有此列表中的模块未使用时才会被保留；所有其他资源在未使用导出时都可以进行 tree-shaking。

  ¥string[]: Array of module IDs that have side effects. Only modules in this list will be preserved if unused; all others can be tree-shaken when their exports are unused.

• 'no-external'：假设外部模块不会产生副作用，同时保留本地模块的默认行为。

  ¥'no-external': Assumes no external modules have side effects while preserving the default behavior for local modules.

• ModuleSideEffectsRule[]：具有 test、external 和 sideEffects 属性的规则数组，用于细粒度控制。

  ¥ModuleSideEffectsRule[]: Array of rules with test, external, and sideEffects properties for fine-grained control.

• function：接收 (id, external) 并返回模块是否有副作用的函数。

  ¥function: Function that receives (id, external) and returns whether the module has side effects.

重要提示：将其设置为 false 或使用数组/字符串，即假定你的模块及其依赖除了导出之外没有其他副作用。仅当你确定删除未使用的模块不会破坏你的应用时才使用此功能。

¥Important: Setting this to false or using an array/string assumes that your modules and their dependencies have no side effects other than their exports. Only use this if you're certain that removing unused modules won't break your application.

性能：优先使用 `ModuleSideEffectsRule[]` 而不是函数

¥[!NOTE] Performance: Prefer ModuleSideEffectsRule[] over functions

尽可能使用基于规则的配置，而不是函数。规则完全在 Rust 中处理，而 JavaScript 函数需要在 Rust 和 JavaScript 之间进行运行时调用，这可能会影响构建期间的 CPU 利用率。

¥When possible, use rule-based configuration instead of functions. Rules are processed entirely in Rust, while JavaScript functions require runtime calls between Rust and JavaScript, which can hurt CPU utilization during builds.

函数应该是最后的手段：仅当你的逻辑无法用模式或简单的字符串匹配来表达时，才使用函数签名。

¥Functions should be a last resort: Only use the function signature when your logic cannot be expressed with patterns or simple string matching.

规则优势：ModuleSideEffectsRule[] 通过避免 Rust-JavaScript 运行时调用、更清晰的意图和更易于维护，从而提供更好的性能。

¥Rule advantages: ModuleSideEffectsRule[] provides better performance by avoiding Rust-JavaScript runtime calls, clearer intent, and easier maintenance.

示例：

¥Examples:

// Assume no modules have side effects (aggressive tree-shaking)
treeshake: {
  moduleSideEffects: false
}

// Only specific modules have side effects (string array)
treeshake: {
  moduleSideEffects: [
    'lodash',
    'react-dom',
  ];
}

// Use rules for pattern matching and granular control
treeshake: {
  moduleSideEffects: [
    { test: /^node:/, sideEffects: true },
    { test: /\.css$/, sideEffects: true },
    { test: /some-package/, sideEffects: false, external: false },
  ];
}

// Custom function to determine side effects
treeshake: {
  moduleSideEffects: ((id, external) => {
    if (external) return false; // external modules have no side effects
    return id.includes('/side-effects/') || id.endsWith('.css');
  });
}

// Assume no external modules have side effects
treeshake: {
  moduleSideEffects: 'no-external',
}

常见用例：

¥Common Use Cases:

• CSS 文件：{ test: /\.css$/, sideEffects: true } - 保留 CSS 导入

  ¥CSS files: { test: /\.css$/, sideEffects: true } - preserve CSS imports

• Polyfill：将特定的 polyfill 模块添加到数组。

  ¥Polyfills: Add specific polyfill modules to the array

• 插件：导入时全局注册的模块

  ¥Plugins: Modules that register themselves globally on import

• 库开发：对于需要移除未使用导出的库，设置为 false。

  ¥Library development: Set to false for libraries where unused exports should be removed

treeshake.annotations

• 类型：boolean

  ¥Type: boolean

• 默认值：true

  ¥Default: true

是否在代码中遵循 /*@__PURE__*/ 注解和其他 tree-shaking 提示。

¥Whether to respect /*@__PURE__*/ annotations and other tree-shaking hints in the code.

treeshake.manualPureFunctions

• 类型：readonly string[]

  ¥Type: readonly string[]

• 默认值：[]

  ¥Default: []

即使无法自动检测为纯函数，也应将其视为纯函数（无副作用）的函数名称数组。

¥Array of function names that should be considered pure (no side effects) even if they can't be automatically detected as pure.

示例：

¥Example:

treeshake: {
  manualPureFunctions: ['console.log', 'debug.trace'];
}

treeshake.unknownGlobalSideEffects

• 类型：boolean

  ¥Type: boolean

• 默认值：true

  ¥Default: true

是否假设访问未知的全局属性可能会产生副作用。

¥Whether to assume that accessing unknown global properties might have side effects.

treeshake.commonjs

• 类型：boolean

  ¥Type: boolean

• 默认值：true

  ¥Default: true

是否为 CommonJS 模块启用 tree-shaking。当 true 设置为 true 时，可以从 bundle 中删除 CommonJS 模块中未使用的导出，类似于 ES 模块。禁用后，CommonJS 模块将始终完整包含在内。

¥Whether to enable tree-shaking for CommonJS modules. When true, unused exports from CommonJS modules can be eliminated from the bundle, similar to ES modules. When disabled, CommonJS modules will always be included in their entirety.

此选项允许 Rolldown 分析 CommonJS 模块中的 exports.property 赋值并删除未使用的导出，同时保留模块的副作用。

¥This option allows rolldown to analyze exports.property assignments in CommonJS modules and remove unused exports while preserving the module's side effects.

示例：

¥Example:

// source.js (CommonJS)
exports.used = 'This will be kept';
exports.unused = 'This will be tree-shaken away';

// main.js
import { used } from './source.js';

// With commonjs: true, only the 'used' export is included in the bundle
// With commonjs: false, both exports are included

treeshake.propertyReadSideEffects

• 类型：false | 'always'

  ¥Type: false | 'always'

• 默认值：false

  ¥Default: false

控制从对象读取属性是否被视为具有副作用。设置为 'always' 可实现更保守的行为。

¥Controls whether reading properties from objects is considered to have side effects. Set to 'always' for more conservative behavior.

treeshake.propertyWriteSideEffects

• 类型：false | 'always'

  ¥Type: false | 'always'

• 默认值：'always'

  ¥Default: 'always'

控制将属性写入对象是否被视为具有副作用。设置为 'always' 可实现保守行为。

¥Controls whether writing properties to objects is considered to have side effects. Set to 'always' for conservative behavior.