close
Rslib
指南
配置
指南
配置
简体中文

lib.redirect

INFO

redirect 是 bundleless 模式（将 lib.bundle 设置为 false）的特定配置。在 bundle 模式下不会生效，因为所有产物文件都被打包成一个文件。所以，导入路径不存在因而不需要重定向。

由于 bundleless 模式仍在开发中，未来将引入更多的重定向配置。

  • 类型：
type JsRedirect = {
  path?: boolean;
  extension?: boolean;
};

type StyleRedirect = {
  path?: boolean;
  extension?: boolean;
};

type Redirect = {
  js?: JsRedirect;
  style?: StyleRedirect;
};
  • 默认值：
const defaultRedirect = {
  js: {
    path: true,
    extension: true,
  },
  style: {
    path: true,
    extension: true,
  },
  asset: true,
};

配置产物文件中导入路径的重定向。在 bundleless 模式下，通常需要使用别名或自动添加 ESM 产物的后缀。redirect 配置旨在解决这些问题。

常见的需要 redirect 的场景：

  • 自动将 tsconfig.json 中 compilerOptions.paths 转换为正确的相对路径

    例如，在 tsconfig.json 中将 compilerOptions.paths 设置为 { "@/*": ["src/*"] }，产物文件将被重定向到正确的相对路径：

    import { foo } from '@/foo'; // './src/bar.ts' 的源码 ↓
import { foo } from './foo.js'; // './dist/bar.js' 预期生成的代码

import { foo } from '@/foo'; // './src/utils/index.ts' 的源码 ↓
import { foo } from '../foo.js'; // './dist/utils/index.js' 预期生成的代码

  • 自动添加文件后缀

    对于在 Node.js 中运行的 ESM 产物，必须指定模块导入的完整路径才能正确加载。Rslib 将根产物文件自动添加后缀。

    import { foo } from './foo'; // './src/bar.ts'  的源码 ↓
import { foo } from './foo.mjs'; // './dist/bar.js' 预期生成的代码

import { foo } from './foo.ts'; // './src/utils/index.ts' 的源码 ↓
import { foo } from './foo.mjs'; // './dist/utils/index.js' 预期生成的代码

redirect.js

控制 JavaScript 产物文件导入路径的重定向。

WARNING

当 output.externals 被配置且请求被匹配时，redirect.js.path 和 redirect.js.extension 都不会生效，最终重写的请求路径将完全由 output.externals 控制。

redirect.js.path

是否自动重定向 JavaScript 产物文件的导入路径。

  • 类型: boolean
  • 默认值: true

当设置为 true 时，resolve.alias 和 resolve.aliasStrategy 将生效并应用于产物文件的重写导入路径。对于 TypeScript 项目，您只需在 tsconfig.json 文件中配置 compilerOptions.paths。

当设置为 false 时，导入路径将不受 resolve.alias、resolve.aliasStrategy 和 tsconfig.json 的影响。

redirect.js.extension

是否根据 JavaScript 产物文件自动重定向文件扩展名到导入路径。

  • 类型: boolean
  • 默认值: true

当设置为 true 时，无论原始扩展名或导入路径中是否指定，文件扩展名都将自动添加到产物文件的重写导入路径中。

当设置为 false 时，文件扩展名将保持原始导入路径（无论是否指定或指定为任意值）。

redirect.style

控制样式产物文件导入路径的重定向。

redirect.style.path

是否自动重定向样式产物文件的导入路径，规则与 redirect.js.path 相同。

  • 类型: boolean

  • 默认值: true

  • 示例：

导入普通样式文件时：

import '@/foo.css'; // './src/bar.ts' 的源码 ↓
import './foo.css'; // './dist/bar.js' 预期生成的代码

import '@/foo.css'; // './src/utils/index.ts' 的源码 ↓
import '../foo.css'; // './dist/utils/index.js' 预期生成的代码

导入 CSS Modules 时：

import styles from '@/foo.css'; // './src/bar.ts' 的源码 ↓
import styles from './foo.css'; // './dist/bar.js' 预期生成的代码

import styles from '@/foo.css'; // './src/utils/index.ts' 的源码 ↓
import styles from '../foo.css'; // './dist/utils/index.js' 预期生成的代码

redirect.style.extension

是否根据样式产物文件自动重定向文件扩展名到导入路径。

  • 类型: boolean
  • 默认值: true

当设置为 true 时，导入普通样式文件的文件扩展名将被重写为 .css，导入 CSS Modules 时，路径将被重写为到对应的 JavaScript 产物文件。

当设置为 false 时，文件扩展名将保持原始导入路径。

  • 示例：

默认情况下，当从 .less 文件导入时：

import './index.less'; // 源码 ↓
import './index.css'; // 预期生成的代码

import styles from './index.module.less'; // 源码 ↓
import styles from './index.module.mjs'; // 预期生成的代码

redirect.asset

当设置为 true 时，导入资源文件的路径将被重写到对应的 JavaScript 产物文件。

当设置为 false 时，文件扩展名将保持原始导入路径。

import url from './assets/logo.svg'; // 源码 ↓
import url from './assets/logo.mjs'; // 预期生成的代码