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

# dev.assetPrefix

- **类型：** `boolean | string | 'auto'`
- **默认值：** [server.base](/zh/config/server/base.md)

设置 [开发模式](/zh/config/mode.md) 下的静态资源 URL 前缀。

`assetPrefix` 会影响构建产物中绝大部分静态资源的 URL，包括 JavaScript 文件、CSS 文件、图片、视频等。如果指定了一个错误的值，则在加载这些资源时可能会出现 404 错误。

该配置项仅用于 `development` 模式。在 `production` 模式或 `none` 模式下，请使用 [output.assetPrefix](/zh/config/output/asset-prefix.md) 配置项进行设置。

## 默认值

`dev.assetPrefix` 的默认值与 [server.base](/zh/config/server/base.md) 相同。

当 `server.base` 为 `/foo` 时，可通过 `http://localhost:3000/foo/` 访问到 `index.html` 及其他静态资源产物。

需要注意的是，当自定义 `dev.assetPrefix` 选项时，如果希望静态资源能够通过 Rsbuild 开发服务器正常访问到，`dev.assetPrefix` 应和 `server.base` 包含相同的 URL 前缀，如：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: '/foo/bar/',
  },
  server: {
    base: '/foo',
  },
};
```

## Boolean 类型

- `true`：根据开发服务器的协议（[server.https](/zh/config/server/https.md)）、主机名（[server.host](/zh/config/server/host.md)）、实际监听端口和 [server.base](/zh/config/server/base.md) 生成绝对 URL 前缀。
- `false`：使用 `/` 作为资源前缀。

例如，设置为 `true` 且使用默认服务器配置时，前缀为 `http://localhost:<port>/`：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: true,
  },
};
```

在浏览器中加载的资源 URL 如下：

```html
<script defer src="http://localhost:3000/static/js/index.js"></script>
```

## String 类型

当 `assetPrefix` 的值为 `string` 类型时，字符串会作为前缀，自动拼接到静态资源访问 URL 上。

- 比如设置为相对于根目录的路径：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: '/example/',
  },
};
```

在浏览器中加载的资源 URL 如下：

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

- 比如设置为完整 URL：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: 'https://example.com/assets/',
  },
};
```

在浏览器中加载的资源 URL 如下：

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

### 端口号占位符

Rsbuild server 监听的端口号可能会发生变更。比如，当端口被占用时，Rsbuild 会自动递增端口号，直至找到一个可用端口。

为了避免端口变化导致 `dev.assetPrefix` 失效，你可以使用以下方法之一：

- 开启 [server.strictPort](/zh/config/server/strict-port.md)。
- 使用 `<port>` 占位符来指代当前端口号，Rsbuild 会将占位符替换为实际监听的端口号。

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: 'http://localhost:<port>/',
  },
};
```

## 路径类型

assetPrefix 可以设置为以下类型的路径：

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

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

## 对比 `publicPath`

`dev.assetPrefix` 的功能与 Rspack 的 [output.publicPath](https://rspack.rs/zh/config/output#outputpublicpath) 配置基本一致。

它与原生配置的区别在于：

- `dev.assetPrefix` 仅在开发模式下生效。
- `dev.assetPrefix` 默认值与 [server.base](/zh/config/server/base.md) 相同。
- `dev.assetPrefix` 默认会自动补全尾部的 `/`。
- `dev.assetPrefix` 的值会写入 [process.env.ASSET\_PREFIX](/zh/guide/advanced/env-vars.md#processenvasset_prefix) 环境变量（只能在 client 代码中访问）。

## 动态 asset prefix

使用 Rspack 提供的 `import.meta.rspackPublicPath` 变量，可以在 JavaScript 代码中动态设置静态资源 URL 的前缀。

详见 [Rspack - 动态设置 publicPath](https://rspack.rs/zh/guide/features/asset-base-path#%E5%8A%A8%E6%80%81%E8%AE%BE%E7%BD%AE-publicpath)。