close
Rslib
  • 简体中文

      • lib.redirect

      Info

      redirect 是 bundleless 模式 的特定配置。该配置在 bundle 模式下不会生效，因为所有产物文件都被打包成一个文件，不需要进行文件导入路径的重定向。

      • 类型：
      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;
};
      • 默认值：
      const defaultRedirect = {
  js: {
    path: true,
    extension: true,
  },
  style: {
    path: true,
    extension: true,
  },
  asset: {
    path: true,
    extension: true,
  },
  dts: {
    path: true,
    extension: false,
  },
};

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

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

      redirect.js

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

      • 示例：

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

      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 被配置且请求被匹配时，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 的影响。

      • 示例：

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

      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 配置有关。

      • 示例：

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

      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 时，文件扩展名将被重写为对应的 JavaScript 产物文件扩展名。

      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 相同。

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

      • 示例：

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

      导入普通样式文件时：

      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

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

      • 示例：

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

      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 相同。

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

      • 示例：

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

      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 时，文件扩展名将保持原始导入路径。

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

      在 JavaScript 文件中引用静态资源的方式及对应的产物结构，请查看 引用静态资源。

      redirect.dts

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

      • 示例：

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

      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，将类型声明产物文件中的导入路径重定向为对应的相对路径。

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

      • 示例：

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

      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
      • 默认值: false

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

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

      Note

      TypeScript 类型文件的扩展名与 dts.autoExtension 配置有关。

      • 示例：

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

      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' 预期生成的代码