Skip to content

Commit

Permalink
docs: improve output.assetPrefix (#3620)
Browse files Browse the repository at this point in the history
  • Loading branch information
chenjiahan committed Oct 2, 2024
1 parent e1d056c commit 09e937f
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 7 deletions.
25 changes: 22 additions & 3 deletions website/docs/en/config/output/asset-prefix.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ This config is only used in production mode. In development mode, please use the

## Example

After setting, the URLs of JavaScript, CSS and other static files will be prefixed with `output.assetPrefix`:
Setting `output.assetPrefix` will add the value as a prefix to the URLs of all static assets like JavaScript, CSS, images, etc.

- For example, setting it to a CDN address:

```js
export default {
Expand All @@ -21,15 +23,31 @@ export default {
};
```

After building, you can see that the JS files are loaded from:
After the build, the URL of the JS file will be:

```html
<script
defer
src="https://cdn.example.com/assets/static/js/main.ebc4ff4f.js"
src="https://cdn.example.com/assets/static/js/index.ebc4ff4f.js"
></script>
```

- Setting it to a relative path:

```js
export default {
output: {
assetPrefix: './',
},
};
```

After the build, the URL of the JS file will be:

```html
<script defer src="./static/js/index.ebc4ff4f.js"></script>
```

## Default Value

The default value of `output.assetPrefix` is the same as [server.base](/config/server/base).
Expand All @@ -54,6 +72,7 @@ export default {
assetPrefix can be set to the following types of paths:

- **absolute path**: This is the most common practice, can be specific server paths, like `/assets/`, or setting to CDN paths, like `https://cdn.example.com/assets/`.
- **relative path**: such as `./assets/`.
- **'auto'**: Rspack will automatically calculate the path and generate relative paths based on file location.

:::tip
Expand Down
27 changes: 23 additions & 4 deletions website/docs/zh/config/output/asset-prefix.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@

## 示例

设置后,项目的 JavaScript、CSS、图片等静态资源的 URL 都会加上 `output.assetPrefix` 作为前缀:
设置 `output.assetPrefix` 后,JavaScript、CSS、图片等静态资源的 URL 都会加上 `output.assetPrefix` 的值作为前缀。

- 例如,设置为一个 CDN 地址:

```js
export default {
Expand All @@ -21,15 +23,31 @@ export default {
};
```

构建之后,可以看到 JS 文件从以下地址加载
构建后,JS 文件的 URL 如下

```html
<script
defer
src="https://cdn.example.com/assets/static/js/main.ebc4ff4f.js"
src="https://cdn.example.com/assets/static/js/index.ebc4ff4f.js"
></script>
```

- 设置为相对路径:

```js
export default {
output: {
assetPrefix: './',
},
};
```

构建后,JS 文件的 URL 如下:

```html
<script defer src="./static/js/index.ebc4ff4f.js"></script>
```

## 默认值

`output.assetPrefix` 的默认值与 [server.base](/config/server/base) 相同。
Expand All @@ -54,10 +72,11 @@ export default {
assetPrefix 可以设置为以下类型的路径:

- **绝对路径**:这是最常见的做法,可以为指定服务器路径,比如 `/assets/`,或是设置为 CDN 路径,比如 `https://cdn.example.com/assets/`
- **相对路径**:比如 `./assets/`
- **'auto'**:Rspack 将自动计算路径,并生成基于文件所在位置的相对路径。

:::tip
不建议将 assetPrefix 设置为相对路径,比如 `'./assets/'`因为当资源位于不同的路径深度时,使用相对路径可能会导致资源无法正确加载。
通常不建议将 assetPrefix 设置为相对路径,因为当资源位于不同的路径深度时,使用相对路径可能会导致资源无法正确加载。
:::

## 对比 `publicPath`
Expand Down

0 comments on commit 09e937f

Please sign in to comment.