Dev Config#

本章节描述了 Builder 中与本地开发有关的配置。

dev.assetPrefix#

• 类型： boolean | string
• 默认值： '/'

设置开发环境下的静态资源 URL 前缀。

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

该配置项仅用于开发环境。在生产环境下，请使用 output.assetPrefix 配置项进行设置。

Boolean 类型#

如果设置 assetPrefix 为 true，Builder 会使用 http://localhost:port/ 作为 URL 前缀：

export default {
  dev: {
    assetPrefix: true,
  },
};

对应 JS 文件在浏览器中加载的地址如下：

<script defer src="http://localhost:8080/static/js/main.js"></script>

如果设置 assetPrefix 为 false 或不设置，则默认使用 / 作为访问前缀。

String 类型#

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

export default {
  dev: {
    assetPrefix: 'http://example.com/assets/',
  },
};

对应 JS 文件在浏览器中加载的地址如下：

<script defer src="http://example.com/assets/static/js/main.js"></script>

与原生配置的区别#

dev.assetPrefix 对应以下原生配置：

• webpack 的 output.publicPath 配置。
• Rspack 的 output.publicPath 配置。

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

• dev.assetPrefix 仅在开发环境下生效。

• dev.assetPrefix 默认会自动补全尾部的 /。

• dev.assetPrefix 的值会写入 process.env.ASSET_PREFIX 环境变量。

dev.beforeStartUrl#

• 类型： () => Promise<void> | void
• 默认值： undefined

dev.beforeStartUrl 用于在打开 startUrl 前执行一段回调函数，该配置项需要与 dev.startUrl 一同使用。

export default {
  dev: {
    startUrl: true,
    beforeStartUrl: async () => {
      await doSomeThing();
    },
  },
};

dev.hmr#

• 类型： boolean
• 默认值： true

是否开启 Hot Module Replacement 热更新能力。

当 hmr 设置为 false 时，将不再提供热更新和 react-refresh 功能。

export default {
  dev: {
    hmr: false,
  },
};

dev.host#

• 类型： string
• 默认值： 0.0.0.0

指定 dev server 启动时监听的 host。

默认情况下，dev server 会监听 0.0.0.0，这代表监听所有的网络接口，包括 localhost 和公网地址。

如果你希望 dev server 只监听 localhost，可以设置为：

export default {
  dev: {
    host: 'localhost',
  },
};

dev.https#

• 类型： boolean | { key: string; cert: string }
• 默认值： false

配置该选项后，可以开启 Dev Server 对 HTTPS 的支持，同时会禁用 HTTP 服务器。

开启前：

> Local:    http://localhost:8080/
  > Network:  http://192.168.0.1:8080/

开启后：

> Local:    https://localhost:8080/
  > Network:  https://192.168.0.1:8080/

自动生成证书#

你可以直接将 https 设置为 true，Builder 会基于 devcert 来自动生成 Dev Server 所需的 HTTPS 证书。

使用这种方式时，你需要在当前项目中手动安装 devcert 依赖：

# npm
npm install devcert@1.2.2 -D

# yarn
yarn add devcert@1.2.2 -D

# pnpm
pnpm add devcert@1.2.2 -D

然后配置 dev.https 为 true 即可：

export default {
  dev: {
    https: true,
  },
};

该方式有一定局限性，由于 devcert 目前不支持 IP addresses，因此访问 Network 域名时，会遇到「您的连接不是私密连接」的问题。

此问题的解决方法为：点击 Chrome 浏览器问题页面的「高级」->「继续前往 192.168.0.1（不安全）」。

手动设置证书#

你也可以在 dev.https 选项中手动传入 HTTPS 服务器所需要的证书和对应的私钥，这个参数将直接传递给 Node.js 中 https 模块的 createServer。

具体可以参考 https.createServer。

import fs from 'fs';

export default {
  dev: {
    https: {
      key: fs.readFileSync('certificates/private.pem'),
      cert: fs.readFileSync('certificates/public.pem'),
    },
  },
};

dev.port#

• 类型： number
• 默认值： 8080

设置 Dev Server 监听的端口号。

默认情况下，Dev Server 会监听 8080 端口，并在端口被占用时自动递增端口号。

示例#

将端口设置为 3000：

export default {
  dev: {
    port: 3000,
  },
};

dev.progressBar#

• 类型：

type ProgressBar =
  | boolean
  | {
      id?: string;
    };

• 默认值： true

是否在编译过程中展示进度条。

export default {
  dev: {
    progressBar: false,
  },
};

如果需要修改进度条左侧显示的文本内容，可以设置 id 选项：

export default {
  dev: {
    progressBar: {
      id: 'Some Text',
    },
  },
};

dev.startUrl#

• 类型： boolean | string | string[] | undefined
• 默认值： undefined

dev.startUrl 用于设置 Dev Server 启动时自动在浏览器中打开的页面 URL。

默认情况下，Dev Server 启动时不会打开任何页面。

你可以设置为如下的值：

export default {
  dev: {
    // 打开项目的默认页面，等价于 `http://localhost:<port>`
    startUrl: true,
    // 打开指定的页面
    startUrl: 'http://localhost:8080',
    // 打开多个页面
    startUrl: ['http://localhost:8080', 'http://localhost:8080/about'],
  },
};

端口号占位符#

由于端口号可能会发生变动，你可以使用 <port> 占位符来指代当前端口号，Builder 会自动将占位符替换为实际监听的端口号。

export default {
  dev: {
    startUrl: 'http://localhost:<port>/home',
  },
};

打开指定浏览器#

在 MacOS 上，通过设置环境变量 BROWSER，你可以指定 Dev Server 在启动时打开的浏览器，支持如下的值：

• Google Chrome Canary
• Google Chrome Dev
• Google Chrome Beta
• Google Chrome
• Microsoft Edge
• Brave Browser
• Vivaldi
• Chromium

建议设置在.env.local文件中。