#从 0.x 升级到 v1

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

#Agent prompt

如果你正在使用 Coding Agent，可以复制以下 prompt 并发送给它：

#升级 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';
        },
      },
    },
  ],
};

#默认环境变量处理更新

在 Rslib v0.x 中，以下 Rsbuild 默认环境变量 会在构建时被替换为指定的值：

• import.meta.env.MODE
• import.meta.env.DEV
• import.meta.env.PROD
• import.meta.env.SSR
• import.meta.env.BASE_URL
• import.meta.env.ASSET_PREFIX
• process.env.BASE_URL
• process.env.ASSET_PREFIX

Rslib v1 更改了这些变量在 format 为 'esm' 和 'cjs' 时的处理方式：

有关 Rslib v1 的完整环境变量处理行为，请参考 环境变量。

如果项目依赖 Rslib v0.x 的构建时替换行为，可以通过 source.define 显式定义实际使用的变量，以恢复原有行为。如果需要在 CJS 产物中使用 import.meta.env.*，也需要显式定义对应的变量：

export default {
  source: {
    define: {
      'import.meta.env.MODE': JSON.stringify('production'),
      'process.env.BASE_URL': JSON.stringify('/'),
      'process.env.ASSET_PREFIX': JSON.stringify(''),
    },
  },
};

#资源模块处理更新

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

#new URL() 静态资源

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

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

对于项目源码，Rslib v0.x 会原样保留该表达式，且不会输出 logo.svg。Rslib v1 则会输出该文件，并将 new URL() 中的路径改写为指向该资源文件的相对路径。

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

对于被打包到产物中的三方依赖，Rslib v0.x 会将 new URL() 中的资源路径改写为模块引用，并在产物中注入用于加载该模块和计算基准 URL 的运行时代码。Rslib v1 则会采用与项目源码相同的处理方式，输出引用的资源，并将 new URL() 中的路径改写为指向该资源文件的相对路径。

如果项目原先通过 output.copy 配置或脚本复制这些资源，且升级后这些资源会由 Rslib 根据 new URL() 引用输出，应移除相应配置或脚本，避免重复输出。在 bundleless 模式（bundle: false）下，如果 source.entry 也会匹配这些资源，还应将它们排除，避免为同一文件额外生成 JavaScript 入口。

如果需要跳过 Rslib 对 new URL() 引用的静态资源处理，可以根据作用范围选择以下方式，详情可以参考 跳过 new URL() 处理。

• 跳过单个引用：在 new URL() 的第一个参数前添加 rspackIgnore 注释。

  src/index.ts

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

• 跳过所有引用：通过 tools.bundlerChain 将 rslib:new-url 规则中的 url parser 选项设置为 false。

  rslib.config.ts

  import { defineConfig } from '@rslib/core';
  
  export default defineConfig({
    tools: {
      bundlerChain(chain) {
        chain.module.rule('rslib:new-url').parser({
          url: false,
        });
      },
    },
  });

此外，Rslib 的默认处理要求 new URL() 的引用目标在构建时能够解析为现有源文件，目录或仅在构建产物中存在的文件无法作为静态资源处理。例如：

const currentDirectory = new URL('.', import.meta.url);
const generatedFile = new URL('./generated.js', import.meta.url);

对于这类引用，可以使用上述方式跳过 new URL() 处理。如果这些引用只是为了在 Node.js 中获取文件系统路径，也可以通过修改源码，改用 Node.js 的 path 和 url API：

import path from 'node:path';
import { fileURLToPath } from 'node:url';

const currentDirectory = path.dirname(fileURLToPath(import.meta.url));
const generatedFile = path.join(currentDirectory, 'generated.js');

更多详情请参考 静态资源 - 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'),
        ),
      },
    },
  ],
};

#临时类型声明目录调整

在类型打包过程中，Rslib 会生成临时类型声明文件。Rslib v1 对这些文件所在的目录进行了调整，由 .rslib/declarations 改为 .rstack/declarations。升级后，可以安全删除旧的 .rslib 目录。

#Node.js 模板更新

Rslib v1 不再提供 ESM/CJS 双格式的 Node.js 模板，仅提供纯 ESM 模板。创建项目时，--template 参数需要按下表更新：

例如，使用原纯 ESM 模板的命令需要按如下方式更新：

-npx create-rslib my-project --template node-esm
+npx create-rslib my-project --template node

此外，新模板默认将 engines.node 设置为 ^20.19.0 || >=22.12.0，并且不再显式配置 lib.syntax。Rslib 会根据 engines.node 自动推断 lib.syntax，详情请参考默认语法目标更新。

engines.node 覆盖的 Node.js 版本均支持 require(ESM)，因此原有的 CommonJS 消费者现在可以直接通过 require() 加载纯 ESM 包，前提是入口及其依赖不使用顶层 await：

const packageExports = require('pure-esm-package');

如果仍需要 ESM/CJS 双格式模板，可以通过以下命令使用旧版生成器创建：

npx -y create-rslib@0.23.2 my-project --template node-dual

#配置

#默认开启 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' 的库配置。