From 81e5bbebde1b77acfc25b0c70bc3085d6464ea8b Mon Sep 17 00:00:00 2001 From: Timeless0911 <1604889533@qq.com> Date: Thu, 20 Mar 2025 19:11:39 +0800 Subject: [PATCH] docs: enhance `output.assetPrefix` --- .../integration/style/sass/bundle-false/rslib.config.ts | 1 - website/docs/en/config/rsbuild/output.mdx | 9 ++++++++- website/docs/en/guide/advanced/static-assets.mdx | 6 +++--- website/docs/zh/config/rsbuild/output.mdx | 9 ++++++++- website/docs/zh/guide/advanced/static-assets.mdx | 6 +++--- 5 files changed, 22 insertions(+), 9 deletions(-) diff --git a/tests/integration/style/sass/bundle-false/rslib.config.ts b/tests/integration/style/sass/bundle-false/rslib.config.ts index 9a059b5b2..da4589944 100644 --- a/tests/integration/style/sass/bundle-false/rslib.config.ts +++ b/tests/integration/style/sass/bundle-false/rslib.config.ts @@ -39,6 +39,5 @@ export default defineConfig({ ], output: { target: 'web', - assetPrefix: 'auto', }, }); diff --git a/website/docs/en/config/rsbuild/output.mdx b/website/docs/en/config/rsbuild/output.mdx index 6f6ab05f4..028de9e39 100644 --- a/website/docs/en/config/rsbuild/output.mdx +++ b/website/docs/en/config/rsbuild/output.mdx @@ -8,7 +8,14 @@ Options for build outputs. Use this option to set the URL prefix for static assets, such as setting it to a CDN URL. -When [format](/config/lib/format) is set to `cjs` or `esm`, Rslib defaults to setting `output.assetPrefix` to `"auto"`. +In Rslib, the default value for this option depends on [format](/config/lib/format): + +- When `format` is `cjs` or `esm`, the default value is `"auto"`. +- When `format` is `mf` or `umd`, the default value is `"/"`. + +When `output.assetPrefix` is set to `"auto"`, Rslib defaults to setting [importMode](https://rspack.dev/config/module#modulegeneratorassetimportmode) to `"preserve"`, which preserves the `import` or `require` statements for static assets in JavaScript files. Additionally, the static asset references in CSS files remain as relative paths, see [Import static assets](/guide/advanced/static-assets) for more details. + +When `output.assetPrefix` is set to a specific path, the static asset import statements in JavaScript files will no longer be preserved and will be replaced with URLs prefixed by that path. Additionally, the static asset paths in CSS files will be substituted with paths that include this prefix. ## output.charset diff --git a/website/docs/en/guide/advanced/static-assets.mdx b/website/docs/en/guide/advanced/static-assets.mdx index 69df68e2a..66612a8bb 100644 --- a/website/docs/en/guide/advanced/static-assets.mdx +++ b/website/docs/en/guide/advanced/static-assets.mdx @@ -13,9 +13,9 @@ The following are the formats supported by Rslib by default: To import assets in other formats, refer to [Extend Asset Types](#extend-asset-types). -## Import assets in JS file +## Import assets in JavaScript file -In JS files, you can directly import static assets with relative paths through `import`: +In JavaScript files, you can directly import static assets with relative paths through `import`: ```tsx // Import the logo.png image in the 'src/assets' directory @@ -36,7 +36,7 @@ console.log(logo); // "/static/logo.[hash].png" export default = () => ; ``` -When the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and transforms the source file into a JS file and a static asset file that is emitted according to [output.distPath](/config/rsbuild/output#outputdistpath) by default, which is used to preserve the `import` statements for static assets. +When the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and transforms the source file into a JavaScript file and a static asset file that is emitted according to [output.distPath](/config/rsbuild/output#outputdistpath) by default with preserving the `import` or `require` statements for static assets. The following is an example of usage, assuming the source code is as follows: diff --git a/website/docs/zh/config/rsbuild/output.mdx b/website/docs/zh/config/rsbuild/output.mdx index 189f2827d..0e03409ac 100644 --- a/website/docs/zh/config/rsbuild/output.mdx +++ b/website/docs/zh/config/rsbuild/output.mdx @@ -8,7 +8,14 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge'; 使用该选项设置静态资源的 URL 前缀，比如设置为 CDN 地址。 -在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.assetPrefix` 设置为 `"auto"`。 +在 Rslib 中，该选项的默认值由 [format](/config/lib/format) 决定： + +- 当 `format` 为 `cjs` 或 `esm` 时，默认值为 `"auto"`。 +- 当 `format` 为 `mf` 或 `umd` 时，默认值为 `"/"`。 + +当 `output.assetPrefix` 设置为 `"auto"` 时，Rslib 会自动将 [importMode](https://rspack.dev/zh/config/module#modulegeneratorassetimportmode) 设置为 `"preserve"`，以保留 JavaScript 文件中引用静态资源的 `import` 或 `require` 语句。同时，CSS 文件中的静态资源会保留相对引用路径，详情可以查看 [引用静态资源](/guide/advanced/static-assets)。 + +当 `output.assetPrefix` 设置为具体的路径时，JavaScript 文件中引用静态资源的 `import` 或 `require` 语句会被替换为包含该前缀的 URL。同时，CSS 文件中的静态资源会被直接替换为带有该前缀的路径。 ## output.charset diff --git a/website/docs/zh/guide/advanced/static-assets.mdx b/website/docs/zh/guide/advanced/static-assets.mdx index 9b5483938..a3cdc83b4 100644 --- a/website/docs/zh/guide/advanced/static-assets.mdx +++ b/website/docs/zh/guide/advanced/static-assets.mdx @@ -13,9 +13,9 @@ Rslib 支持在代码中引用图片、字体、音频、视频等类型的静 如果你需要引用其他格式的静态资源，请参考 [扩展静态资源类型](#扩展静态资源类型)。 -## 在 JS 文件中引用 +## 在 JavaScript 文件中引用 -在 JS 文件中，可以直接通过 `import` 的方式引用相对路径下的静态资源： +在 JavaScript 文件中，可以直接通过 `import` 的方式引用相对路径下的静态资源： ```tsx // 引用 src/assets 目录下的 logo.png 图片 @@ -36,7 +36,7 @@ console.log(logo); // "/static/logo.[hash].png" export default = () => ; ``` -在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会在代码转换时将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，从而保留引用静态资源的 `import` 语句。 +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会在代码转换时将源文件转化为一个 JavaScript 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，并保留引用静态资源的 `import` 或 `require` 语句。 下面是一个使用示例，假设源码如下：