> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# lib.redirect

:::info

`redirect` 是 [bundleless 模式](/zh/guide/basic/output-structure.md#bundle--bundleless) 的特定配置。该配置在 bundle 模式下不会生效，因为所有产物文件都被打包成一个文件，不需要进行文件导入路径的重定向。

:::

- **类型：**

```ts
type JsRedirect = {
  path?: boolean;
  extension?: boolean;
};

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

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

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

type Redirect = {
  js?: JsRedirect;
  style?: StyleRedirect;
  asset?: AssetRedirect;
  dts?: DtsRedirect;
};
```

- **默认值：**

```ts
const defaultRedirect = {
  js: {
    path: true,
    extension: true,
  },
  style: {
    path: true,
    extension: true,
  },
  asset: {
    path: true,
    extension: true,
  },
  dts: {
    path: true,
    extension: true,
  },
};
```

- **顶层配置：** 支持

配置产物文件中导入路径的重定向。

在 bundleless 模式下，通常需要使用别名或自动添加 ESM 产物的后缀。`redirect` 配置旨在解决这些问题。

## redirect.js

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

- **示例：**

默认情况下，在 `tsconfig.json` 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }` 时，JavaScript 产物文件的导入路径将被重定向到正确的相对路径并添加对应的文件扩展名。

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

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

:::warning

当 [output.externals](/zh/config/rsbuild/output.md#outputexternals) 被配置且请求被匹配时，`redirect.js.path` 和 `redirect.js.extension` 都不会生效，最终重定向的请求路径将完全由 [output.externals](/zh/config/rsbuild/output.md#outputexternals) 控制。

:::

### redirect.js.path

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

- **类型:** `boolean`
- **默认值:** `true`

当设置为 `true` 时，[resolve.alias](/zh/config/rsbuild/resolve.md#resolvealias) 和 [resolve.aliasStrategy](/zh/config/rsbuild/resolve.md#resolvealiasstrategy) 会在产物文件中生效，产物文件的导入路径会被重写。对于 TypeScript 项目，在 `tsconfig.json` 文件中配置 [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths) 即可。

当设置为 `false` 时，导入路径将不受 [resolve.alias](/zh/config/rsbuild/resolve.md#resolvealias)、[resolve.aliasStrategy](/zh/config/rsbuild/resolve.md#resolvealiasstrategy) 和 `tsconfig.json` 的影响。

- **示例：**

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

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

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

### redirect.js.extension

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

- **类型:** `boolean`
- **默认值:** `true`

当设置为 `true` 时，JavaScript 产物文件中那些可被正确解析的导入路径，其文件扩展名将被自动补全或替换。

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

:::note
JavaScript 产物文件的扩展名与 [autoExtension](/zh/config/lib/auto-extension.md#libautoextension) 配置有关。
:::

- **示例：**

对于在 Node.js 中运行的 ESM 产物，必须要指定模块导入路径的完整扩展名才能正确加载。Rslib 将根据实际的 JavaScript 产物文件自动添加对应的文件扩展名。

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

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

## redirect.style

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

- **示例：**

默认情况下，在 `tsconfig.json` 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }` 时，样式产物文件的导入路径将被重定向到正确的相对路径。此外，在导入 [CSS Modules](/zh/config/rsbuild/output.md#outputcssmodules) 时，文件扩展名将被重写为对应的 JavaScript 产物文件扩展名。

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

import styles from '@/foo.module.less'; // './src/baz.ts' 的源码 ↓
import styles from './foo.module.mjs'; // './dist/baz.mjs' 预期生成的代码
```

### redirect.style.path

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

- **类型:** `boolean`
- **默认值:** `true`

当设置为 `true` 时，相关重定向规则与 [redirect.js.path](/zh/config/lib/redirect.md#redirectjspath) 相同。

当设置为 `false` 时，将保持原始导入路径不变。

- **示例：**

在 `tsconfig.json` 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }` 时，样式产物文件的导入路径将被重定向到正确的相对路径。

导入普通样式文件时：

```ts
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](/zh/config/rsbuild/output.md#outputcssmodules) 时：

```ts
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](/zh/config/rsbuild/output.md#outputcssmodules) 时，文件扩展名将被重写为对应的 JavaScript 产物文件扩展名。

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

- **示例：**

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

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

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

## redirect.asset

控制资源文件导入路径的重定向。

- **示例：**

默认情况下，在 `tsconfig.json` 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }` 时，资源文件的导入路径将被重定向到正确的相对路径，其扩展名将被重写为对应的 JavaScript 产物文件扩展名。

```ts
import url from '@/assets/logo.svg'; // './src/foo.ts' 的源码 ↓
import url from './assets/logo.mjs'; // './dist/foo.mjs' 预期生成的代码
```

### redirect.asset.path

是否自动重定向资源文件的导入路径。

- **类型:** `boolean`
- **默认值:** `true`

当设置为 `true` 时，相关重定向规则与 [redirect.js.path](/zh/config/lib/redirect.md#redirectjspath) 相同。

当设置为 `false` 时，将保持原始导入路径不变。

- **示例：**

在 `tsconfig.json` 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }` 时，资源文件的导入路径将被重定向到正确的相对路径。

```ts
import url from '@/assets/logo.svg'; // './src/foo.ts' 的源码 ↓
import url from './assets/logo.svg'; // './dist/foo.js' 预期生成的代码
```

### redirect.asset.extension

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

- **类型:** `boolean`
- **默认值:** `true`

当设置为 `true` 时，导入资源文件的扩展名将被重写为对应的 JavaScript 产物文件扩展名。

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

- **示例：**

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

::: note

在 JavaScript 文件中引用静态资源的方式及对应的产物结构，请查看 [静态资源](/zh/guide/advanced/static-assets.md#在-javascript-文件中引用)。

:::

## redirect.dts

控制 TypeScript 类型文件中导入路径的重定向。

- **示例：**

默认情况下，在 `tsconfig.json` 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }` 时，类型声明产物文件的导入路径将被重定向到正确的相对路径。

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

### redirect.dts.path

是否自动重定向 TypeScript 类型文件中的导入路径。

- **类型:** `boolean`
- **默认值:** `true`

当设置为 `true` 时，Rslib 会根据 `tsconfig.json` 文件中配置的 [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths)，将类型声明产物文件中的导入路径重定向为对应的相对路径。

当设置为 `false` 时，将保持原始导入路径不变。

- **示例：**

在 `tsconfig.json` 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }` 时，类型声明产物文件中的导入路径将被重定向到正确的相对路径：

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

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

### redirect.dts.extension

是否根据 TypeScript 类型文件自动重定向导入路径的文件扩展名。

- **类型:** `boolean`
- **默认值:** `true`

当设置为 `true` 时，类型声明文件中的导入路径，其文件扩展名会被自动补全或替换为对应的可以解析到相应类型声明文件的 JavaScript 文件扩展名。

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

:::note
TypeScript 类型文件的扩展名与 [dts.autoExtension](/zh/config/lib/dts.md#dtsautoextension) 配置有关。
:::

- **示例：**

当使用 `moduleResolution: 'nodenext'` 加载模块时，导入路径需要包含完整的文件扩展名。Rslib 将根据实际的 JavaScript 产物文件自动添加对应的文件扩展名。

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

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

#### 注意事项

该配置也适用于通过 [`paths`](https://typescriptlang.org/tsconfig#paths) 或 [`dts.alias`](/zh/config/lib/dts.md#dtsalias) 改写后的类型导入路径，因此需要注意以下情况：

- Rslib 会对配置路径进行 `index` 入口探测，但不会根据该目录 `package.json` 中的 `types`、`exports` 的 `types` 条件名称或 `typesVersions` 定位类型入口。若需根据这些包配置定位入口，请将配置路径直接指向具体入口。例如，当 `vendor/foo/package.json` 中配置了 `"types": "./typings/main.d.ts"` 时：

  ```diff title="rslib.config.ts"
   dts: {
     alias: {
  -    foo: './vendor/foo',
  +    foo: './vendor/foo/typings/main',
     },
   },
  ```

- 如果配置路径对应的 CommonJS 类型声明原本使用 `export =`，请保留该导出形式，不要将其转换为 `export default`。否则，从 ESM 类型声明中使用 NodeNext 解析该模块时，CommonJS default interop 可能与显式 default 导出叠加，导致原本的命名空间成员出现在 `default` 下一层。例如：

  ```diff title="foo/index.d.ts"
   declare function Foo(): void;
   declare namespace Foo {
     interface Options {}
   }

  -export { Foo as default };
  +export = Foo;
  ```

未命中 `paths` 或 `dts.alias` 的裸包导入不会被改写，仍由 TypeScript 按正常的包解析流程处理。