实验选项

¥Experimental Options

• 类型：object

  ¥Type: object

• 默认值：查看各个选项

  ¥Default: See individual options

实验性功能可能会在未来版本中发生变化，并且可能在不进行重大版本升级的情况下引入行为变更。

¥Experimental features that may change in future releases and can introduce behavior change without a major version bump.

strictExecutionOrder

• 类型：boolean

  ¥Type: boolean

• 默认值：false

  ¥Default: false

• 路径：experimental.strictExecutionOrder

  ¥Path: experimental.strictExecutionOrder

让模块按声明顺序执行。这是通过注入运行时助手来实现的，以确保模块按照导入的顺序执行。外部模块不会受到影响。

¥Lets modules be executed in the order they are declared. This is done by injecting runtime helpers to ensure that modules are executed in the order they are imported. External modules won't be affected.

深入探讨

¥In-depth

警告

启用此选项可能会对包大小产生负面影响。建议仅在绝对必要时使用此选项。

¥Enabling this option may negatively impact bundle size. It is recommended to use this option only when absolutely necessary.

disableLiveBindings

• 类型：boolean

  ¥Type: boolean

• 默认值：false

  ¥Default: false

• 路径：experimental.disableLiveBindings

  ¥Path: experimental.disableLiveBindings

禁用导出变量的实时绑定。

¥Disable live bindings for exported variables.

viteMode

• 类型：boolean

  ¥Type: boolean

• 默认值：false

  ¥Default: false

• 路径：experimental.viteMode

  ¥Path: experimental.viteMode

启用 Vite 兼容模式。

¥Enable Vite compatibility mode.

resolveNewUrlToAsset

• 类型：boolean

  ¥Type: boolean

• 默认值：false

  ¥Default: false

• 路径：experimental.resolveNewUrlToAsset

  ¥Path: experimental.resolveNewUrlToAsset

将 new URL() 解析为资源引用。

¥Resolve new URL() to asset references.

hmr

• 类型：boolean | { host?: string; port?: number; implement?: string }

  ¥Type: boolean | { host?: string; port?: number; implement?: string }

• 默认值：false

  ¥Default: false

• 路径：experimental.hmr

  ¥Path: experimental.hmr

热模块替换配置。

¥Hot Module Replacement configuration.

示例

¥Examples

export default {
  experimental: {
    hmr: {
      host: 'localhost',
      port: 3000,
    },
  },
};

chunkModulesOrder

• 类型：'exec-order' | 'module-id'

  ¥Type: 'exec-order' | 'module-id'

• 默认值：'exec-order'

  ¥Default: 'exec-order'

• 路径：experimental.chunkModulesOrder

  ¥Path: experimental.chunkModulesOrder

控制在代码块中渲染模块时使用的顺序。

¥Control which order to use when rendering modules in a chunk.

深入探讨

¥In-depth

可用的选项：

¥The available options:

• 'exec-order'：几乎等同于模块图的拓扑顺序，但当模块图存在循环时会进行特殊处理。

  ¥'exec-order': Almost equivalent to the topological order of the module graph, but specially handling when module graph has cycle

• 'module-id'：这对 gzip 压缩更加友好，尤其是对于某些 JavaScript 静态资源库（例如图标库）

  ¥'module-id': This is more friendly for gzip compression, especially for some javascript static asset lib (e.g. icon library)

信息

如果可能，请尝试按模块 ID 对模块进行排序。由于 Rolldown 作用域会提升块中的所有模块，因此只有在排序后能够确保运行时行为正确的情况下，我们才会尝试按模块 ID 对这些模块进行排序。

¥Try to sort the modules by their module id if possible. Since Rolldown scope hoists all modules in the chunk, we only try to sort those modules by module id if we could ensure runtime behavior is correct after sorting.

attachDebugInfo

• 类型：'none' | 'simple' | 'full'

  ¥Type: 'none' | 'simple' | 'full'

• 默认值：'simple'

  ¥Default: 'simple'

• 路径：experimental.attachDebugInfo

  ¥Path: experimental.attachDebugInfo

将调试信息附加到输出包。

¥Attach debug information to the output bundle.

深入探讨

¥In-depth

可用的模式：

¥The available modes:

• 'none'：不附加调试信息

  ¥'none': No debug information is attached

• 'simple'：附加注释，指示打包代码来自哪些文件。这些注释可能会被压缩器删除。

  ¥'simple': Attach comments indicating which files the bundled code comes from. These comments could be removed by the minifier

• 'full'：将详细的调试信息附加到输出包。这些注释使用了合法的注释语法，因此不会被压缩器删除。

  ¥'full': Attach detailed debug information to the output bundle. These comments are using legal comment syntax, so they won't be removed by the minifier

警告

你不应该在生产构建中使用 'full'。

¥You shouldn't use 'full' in the production build.

chunkImportMap

• 类型：boolean | { baseUrl?: string; fileName?: string }

  ¥Type: boolean | { baseUrl?: string; fileName?: string }

• 默认值：false

  ¥Default: false

• 路径：experimental.chunkImportMap

  ¥Path: experimental.chunkImportMap

启用在构建过程中自动生成块导入映射资源。

¥Enables automatic generation of a chunk import map asset during build.

示例

¥Examples

export default {
  experimental: {
    chunkImportMap: {
      baseUrl: '/',
      fileName: 'importmap.json',
    },
  },
  plugins: [
    {
      name: 'inject-import-map',
      generateBundle(_, bundle) {
        const chunkImportMap = bundle['importmap.json'];
        if (chunkImportMap?.type === 'asset') {
          const htmlPath = path.resolve('index.html');
          let html = fs.readFileSync(htmlPath, 'utf-8');

          html = html.replace(
            /<script\s+type="importmap"[^>]*>[\s\S]*?<\/script>/i,
            `<script type="importmap">${chunkImportMap.source}</script>`,
          );

          fs.writeFileSync(htmlPath, html);
          delete bundle['importmap.json'];
        }
      },
    },
  ],
};

深入探讨

¥In-depth

此映射仅包含带有哈希文件名的块，其中键源自外观模块名称或主块名称。它生成稳定且唯一的基于哈希值的文件名，有效防止由内容哈希值导致的级联缓存失效，并最大限度地提高浏览器缓存的重用率。

¥This map only includes chunks with hashed filenames, where keys are derived from the facade module name or primary chunk name. It produces stable and unique hash-based filenames, effectively preventing cascading cache invalidation caused by content hashes and maximizing browser cache reuse.

除非通过 fileName 覆盖，否则输出默认为 importmap.json。可以将基本 URL 前缀（默认为 "/"）应用于所有路径。生成的 JSON 是一个有效的导入映射，可以通过 <script type="importmap"> 直接注入到 HTML 中。

¥The output defaults to importmap.json unless overridden via fileName. A base URL prefix (default "/") can be applied to all paths. The resulting JSON is a valid import map and can be directly injected into HTML via <script type="importmap">.

提示

如果你想了解更多信息，可以查看此处的示例：examples/chunk-import-map

¥If you want to learn more, you can check out the example here: examples/chunk-import-map

onDemandWrapping

• 类型：boolean

  ¥Type: boolean

• 默认值：false

  ¥Default: false

• 路径：experimental.onDemandWrapping

  ¥Path: experimental.onDemandWrapping

启用按需模块封装。

¥Enable on-demand wrapping of modules.

incrementalBuild

• 类型：boolean

  ¥Type: boolean

• 默认值：false

  ¥Default: false

• 路径：experimental.incrementalBuild

  ¥Path: experimental.incrementalBuild

启用增量构建支持。必须与 watch 模式一起使用。

¥Enable incremental build support. Required to be used with watch mode.

transformHiresSourcemap

• 类型：boolean | 'boundary'

  ¥Type: boolean | 'boundary'

• 默认值：false

  ¥Default: false

• 路径：experimental.transformHiresSourcemap

  ¥Path: experimental.transformHiresSourcemap

启用高解析源码映射以进行转换操作。

¥Enable high-resolution source maps for transform operations.

nativeMagicString

• 类型：boolean

  ¥Type: boolean

• 默认值：false

  ¥Default: false

• 路径：experimental.nativeMagicString

  ¥Path: experimental.nativeMagicString

使用 Rust 原生的 MagicString 实现来生成源码映射。

¥Use native Rust implementation of MagicString for source map generation.

示例

¥Examples

export default {
  experimental: {
    nativeMagicString: true,
  },
  output: {
    sourcemap: true,
  },
};

深入探讨

¥In-depth

MagicString 是一个 JavaScript 库，通常被打包器用于字符串操作和源码映射生成。启用后，Rolldown 将使用 MagicString 的原生 Rust 实现（而非 JavaScript 版本），从而在源映射生成和代码转换过程中提供显著更佳的性能。

¥MagicString is a JavaScript library commonly used by bundlers for string manipulation and source map generation. When enabled, Rolldown will use a native Rust implementation of MagicString instead of the JavaScript version, providing significantly better performance during source map generation and code transformation.

优势：

¥Benefits:

• 性能提升：原生 Rust 实现通常比 JavaScript 版本更快，尤其是对于具有大量源码映射的大型代码库。

  ¥Improved Performance: The native Rust implementation is typically faster than the JavaScript version, especially for large codebases with extensive source maps

• 后台处理：源码映射生成在后台线程中异步执行，允许主打包过程继续进行而不会阻塞。在使用 JavaScript 转换钩子时，这种并行处理可以显著缩短整体构建时间。

  ¥Background Processing: Source map generation is performed asynchronously in a background thread, allowing the main bundling process to continue without blocking. This parallel processing can significantly reduce overall build times when working with JavaScript transform hooks

• 更好的集成：与 Rolldown 原生 Rust 架构无缝集成

  ¥Better Integration: Seamless integration with Rolldown's native Rust architecture

信息

这是一个实验性功能。虽然它旨在提供与 JavaScript 实现相同的行为，但可能存在一些边缘情况。请报告你遇到的任何差异。

¥This is an experimental feature. While it aims to provide identical behavior to the JavaScript implementation, there may be edge cases. Please report any discrepancies you encounter.

完整的示例请参见 examples/native-magic-string

¥For a complete working example, see examples/native-magic-string