#从 0.x 升级到 v1

当前文档列出了从 Rslib 0.23 到 1.0 的所有不兼容更新，你可以参考此文档来迁移。

#升级 Rslib 到 v1

将 @rslib/core 升级到 1.0 版本：

{
  "devDependencies": {
    "@rslib/core": "^1.0.0"
  }
}

#Rsbuild v2

Rslib v1 基于 Rsbuild v2，升级时可以通过 peerDependencies 检查项目中的 Rsbuild 插件是否支持 @rsbuild/core v2。推荐使用 Taze 将项目中的 Rsbuild 插件升级到最新版本：

# 升级当前目录中的 Rsbuild 插件
npx taze major --include "/rsbuild/" -w

# 或递归升级整个 monorepo 中的 Rsbuild 插件
npx taze major --include "/rsbuild/" -w -r

如果项目直接使用了 Rsbuild 配置或 JavaScript API，可以参考 Rsbuild v2 升级指南 了解相关变更。

#默认语法目标更新

当 output.target 为 'node' 且未配置 lib.syntax 时，Rslib v1 会尝试根据 package.json#engines.node 推断语法目标。

例如，以下 engines.node：

{
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  }
}

Rslib 会将其解析为以下语法目标：

export default {
  lib: [
    {
      syntax: ['node >= 20.19.0'],
    },
  ],
};

如果 engines.node 不存在或无法推断出最低版本，Rslib 会继续使用 'esnext'。

显式配置的 lib.syntax 优先级高于自动推断，因此已有配置不会受到影响，也可以通过它覆盖根据 engines.node 推断出的目标。

此外，Rslib v1 调整了 es2023 和 es2024 的 Browserslist 基线，并新增了 es2025：

这些配置仅控制 JavaScript 和 CSS 的语法降级，不会为目标环境缺失的运行时 API 注入 polyfill。新基线对 JavaScript 降级的实际影响较小，主要会使 Lightning CSS 输出更现代的 CSS。

如果新的基线符合预期，则无需调整。如果需要保留 Rslib v0.x 的语法目标行为：

• 项目原来使用 es2023，并且需要保留之前较保守的兼容范围：

  rslib.config.ts

  export default {
    lib: [
      {
  -      syntax: 'es2023',
  +      syntax: 'es2022',
      },
    ],
  };

• 项目原来使用 es2024，并且需要继续使用动态的 Browserslist 目标：

  rslib.config.ts

  export default {
    lib: [
      {
  -      syntax: 'es2024',
  +      syntax: 'esnext',
      },
    ],
  };

#默认 externalsType 更新

对于 ESM 产物（format: 'esm'），Rslib v1 将 Rspack 的默认 externalsType: 'module-import' 调整为 externalsType: 'modern-module'：

这项变化只影响在未显式设置 externalsType 时，通过 require() 加载的外部 CommonJS 模块，包括通过 lib.autoExternal、output.autoExternal、output.externals 外部化的依赖，以及 target: 'node' 下自动外部化的 Node.js 内置模块。通过 ESM import 加载的 external 行为不变，通常不需要调整。

需要注意的是，如果产物中包含通过 createRequire() 加载的 external，并且该产物还会被再次打包，消费方的打包器需要能够静态分析这种调用。Rsbuild / Rspack 项目可以开启 module.parser.javascript.createRequire。如果模块加载语义允许，也可以考虑将源码中的 CommonJS require() 改为 ESM import。

如果只需要让某个依赖保留 Rslib v0.x 的行为，并且确认该依赖适用 ESM import 的加载语义，可以在 output.externals 中使用 ${externalsType} ${libraryName} 语法，将该依赖指定为 module-import：

export default {
  lib: [
    {
      output: {
        externals: {
          'some-package': 'module-import some-package',
        },
      },
    },
  ],
};

如果需要保留所有依赖在 Rslib v0.x 中的行为，可以通过 tools.rspack 将 externalsType 设置为 module-import：

export default {
  lib: [
    {
      tools: {
        rspack(config) {
          config.externalsType = 'module-import';
        },
      },
    },
  ],
};

#默认解析 createRequire()

Rslib v1 默认启用 Rspack 的 module.parser.javascript.createRequire，用于解析由 createRequire() 创建的 require 调用。通过这类调用加载的依赖若可被静态分析且未被 external，则会被打包到产物中。

Rslib v0.x 不会解析这类 require 调用，而是将其原样保留在产物中。使用 createRequire(import.meta.url) 时，相对路径会在运行时以产物文件所在目录为基准解析。例如，项目通过单独的构建流程将 src/foo/bar.ts 编译为 dist/bar.js，并在 src/index.ts 中按照该文件在产物中的相对路径进行加载：

import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const bar = require('./bar.js');

Rslib v1 则会在构建时以源码文件所在目录为基准解析相对路径。在上述示例中，./bar.js 会从 src/index.ts 所在目录解析，而不会在运行时加载 dist/bar.js。升级时，可以根据实际需求进行调整：

• 如果模块需要被打包，改为引用实际的源码文件：

  src/index.ts

  -const bar = require('./bar.js');
  +const bar = require('./foo/bar.ts');

• 如果特定依赖不需要被打包，可以通过 output.externals 将其声明为 external。

• 如果希望所有这类调用都原样保留，可以关闭 createRequire 解析：

  rslib.config.ts

  export default {
    tools: {
      rspack: {
        module: {
          parser: {
            javascript: {
              createRequire: false,
            },
          },
        },
      },
    },
  };

#资源模块处理更新

Rslib v1 调整了 ESM 产物（format: 'esm'）中通过 new URL() 引用的静态资源、Web Workers 和 Wasm 模块的处理方式。

#new URL() 静态资源

构建 ESM 产物时，Rslib v1 会将可静态分析的本地 new URL() 引用作为静态资源处理。以引用 logo.svg 为例：

const logo = new URL('./assets/logo.svg', import.meta.url);

Rslib v0.x 会原样保留该表达式，且不会输出 logo.svg。Rslib v1 则会输出该文件，并将 URL 重写为指向该文件的相对路径：

const logo = new URL('./static/svg/logo.svg', import.meta.url);

如果项目此前通过 output.copy 或脚本复制这类资源，升级后应移除相应配置，避免重复输出。在 bundleless 模式（bundle: false）下，还需要在 source.entry 中排除已通过 new URL() 引用的资源，避免为同一文件额外生成 JavaScript 入口。

如果希望恢复 Rslib v0.x 的行为，原样保留所有 new URL() 且不由 Rslib 输出资源，可以关闭 URL parser：

export default {
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        .oneOf(CHAIN_ID.ONE_OF.JS_MAIN)
        .parser({
          url: false,
        });
    },
  },
};

更多详情请参考 静态资源 - new URL 引用。

#Web Workers

构建 ESM 产物时，Rslib v1 会解析 new Worker(new URL(...))，并将其中引用的本地脚本作为 Worker 入口处理。以 worker.ts 为例：

new Worker(new URL('./worker.ts', import.meta.url));

Rslib v0.x 会原样保留该表达式，不会根据这条引用构建 worker.ts。Rslib v1 则会构建 Worker 及其依赖，将 URL 重写为对应的产物路径，并自动添加 type: 'module'：

new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module',
});

如果项目此前将 Worker 源文件配置为独立入口，并在源码中引用预期生成的 .js 文件，升级后可以移除相应入口，改为直接引用 Worker 源文件：

 export default {
   source: {
     entry: {
       index: './src/index.ts',
-      worker: './src/worker.ts',
     },
   },
 };

-new Worker(new URL('./worker.js', import.meta.url));
+new Worker(new URL('./worker.ts', import.meta.url));

更多详情请参考 Web Workers。

#Wasm

Rslib v1 为 ESM 产物中的 Wasm 模块提供了两种输出模式：

• compile 模式：Rslib 会生成加载和实例化 Wasm 模块所需的 JavaScript 代码，并输出带 hash 的 .wasm 文件。
• preserve 模式：JavaScript 中的 .wasm import 会被保留，.wasm 文件则沿用原文件名和相对目录输出，交由支持 WebAssembly ESM Integration 的下游构建工具或目标运行时处理。

在 bundleless 模式 下，Rslib v0.x 会生成加载和实例化 Wasm 模块所需的 JavaScript 代码，Rslib v1 则默认使用 preserve 模式，在 JavaScript 中保留 .wasm import。如需改用 compile 模式，可以配置 wasm.mode：

export default {
  lib: [
    {
      format: 'esm',
      bundle: false,
      wasm: {
        mode: 'compile',
      },
    },
  ],
};

bundle 模式 下的 Wasm 处理行为保持不变。

更多详情请参考 Wasm - 输出模式。

#@typescript/native-preview 支持调整

在 Rslib v0.x 中，开启 dts.tsgo 后，Rslib 会自动加载 @typescript/native-preview 来生成类型声明文件。

Rslib v1 默认不会加载 @typescript/native-preview，而是从项目根目录解析 typescript，并根据解析到的版本选择类型声明生成方式。检测到 TypeScript 7+ 时，Rslib 会自动启用 dts.tsgo。

如果需要继续使用 @typescript/native-preview，可以通过 dts.typescriptPath 显式指定它的模块入口：

import { fileURLToPath } from 'node:url';

export default {
  lib: [
    {
      dts: {
        typescriptPath: fileURLToPath(
          import.meta.resolve('@typescript/native-preview'),
        ),
      },
    },
  ],
};

#配置

#默认开启 redirect.dts.extension

Rslib v1 默认开启了 redirect.dts.extension，在生成 bundleless 类型声明文件时，导入路径会自动补全或替换为可以解析到相应类型声明文件的 JavaScript 文件扩展名。

例如，当导入路径对应 foo.d.ts 时，生成结果如下：

-export type { Foo } from './foo';
+export type { Foo } from './foo.js';

如果你的消费工具依赖不带扩展名的类型导入路径，或由其他工具负责重写扩展名，可以恢复 Rslib 0.x 的行为：

export default {
  lib: [
    {
      redirect: {
        dts: {
          extension: false,
        },
      },
    },
  ],
};

如果你同时配置了 compilerOptions.paths 或 dts.alias，请检查映射后的类型导入路径是否需要直接指向具体的类型声明入口，详情请参考 redirect.dts.extension。

#迁移 lib.autoExternal

lib.autoExternal 已在 Rslib v1 中废弃，但暂未移除，仍可继续使用。

我们推荐使用 Rsbuild 的 output.autoExternal 配置替代它：

 export default {
   lib: [
     {
-      autoExternal: false,
+      output: {
+        autoExternal: false,
+      },
     },
   ],
 };

#移除 experiments.advancedEsm

experiments.advancedEsm 选项已被移除。

该选项原本用于生成对静态分析更友好并支持代码分割的 ESM 产物。但在 Rslib v1 中，这种 ESM 输出已成为默认行为，因此该选项不再需要。

 export default {
   lib: [
     {
-      experiments: {
-        advancedEsm: true,
-      },
     },
   ],
 };

#JavaScript API

• RslibConfig 中 lib 的类型从 LibConfig[] 变为 LibConfig[] | undefined。省略 lib 时，行为等同于配置 lib: [{}]。
• rslib.inspectConfig() 的 mode 选项移除了无效的 'none' 值。未设置 mode 时，现在会根据 process.env.NODE_ENV 推断：当 NODE_ENV 为 'development' 时，mode 为 'development'，否则为 'production'。当 mode 为 'development' 时，rslib.inspectConfig() 现在仅会输出 format: 'mf' 的库配置。