配置 Vite 构建输出的公共基础路径

当 Vite 应用部署到非根目录的子路径时，构建产物（如 JavaScript、CSS 文件）的引用路径可能因默认的根相对路径设置而导致 404 错误。本文将详细介绍如何通过配置 Vite 的 `base` 选项，无论是通过命令行参数还是 `vite.config.js` 文件，来指定正确的公共基础路径，确保应用在任何部署环境下都能正常加载资源。

理解 Vite 构建产物的路径问题

在 Vite 开发模式下（npm run dev），应用通常运行在 http://localhost:3000，资源路径表现正常。然而，当进行生产环境构建（npm run build）并将 dist 目录部署到服务器的某个子文件夹时，例如 http://myapp.com/docs/reconstatus/，问题便会浮现。

Vite 默认生成的资源链接（如 <script src="/assets/index.js"></script> 或 <link href="/assets/style.css" rel="stylesheet">）是以根目录 / 开头的绝对路径。这意味着浏览器会尝试从 http://myapp.com/assets/index.js 加载资源，而不是从 http://myapp.com/docs/reconstatus/assets/index.js。由于实际文件位于子目录中，这会导致资源加载失败，产生 404 错误。

为了解决这个问题，我们需要告诉 Vite 在构建时，为所有生成的资源路径添加一个正确的前缀，使其相对于应用的实际部署路径。这个前缀就是 Vite 的 base 配置项。

配置公共基础路径

Vite 提供了两种主要方式来配置 base 选项：通过命令行参数或在 vite.config.js 配置文件中设置。

方法一：通过命令行参数

最直接的方式是在执行构建命令时，将 base 路径作为参数传递给 Vite。这对于快速测试或在 CI/CD 流程中动态指定路径非常有用。

示例代码：

假设您的应用将部署到 http://myapp.com/docs/reconstatus/ 这个路径下，那么在构建时，您可以这样指定 base：

vite build --base=/docs/reconstatus/

或者，如果您在 package.json 中定义了 build 脚本，可以修改为：

{
  "scripts": {
    "build": "vite build --base=/docs/reconstatus/"
  }
}

说明：

• --base 参数后面跟着的是您应用部署的公共基础路径。
• 路径通常以斜杠 / 开头，表示相对于域名的根目录。
• 建议在路径末尾也加上斜杠，以确保所有子资源路径都能正确拼接。

方法二：在 vite.config.js 中配置

更常见且推荐的做法是在项目的 vite.config.js（或 vite.config.ts）配置文件中定义 base 选项。这种方式将配置固化在项目代码中，易于版本控制和团队协作。

轻舟办公

基于AI的智能办公平台

194

查看详情

示例代码：

在您的 vite.config.js 文件中添加 base 属性：

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  base: '/docs/reconstatus/', // 设置您的公共基础路径
  // 其他 Vite 配置项...
});

说明：

• defineConfig 辅助函数有助于智能提示和类型检查。
• base 属性的值应与您应用实际部署的子目录路径一致。

注意事项与最佳实践

1. 路径格式：

   • base 值通常是一个以 / 开头的绝对路径（相对于域名根目录），并建议以 / 结尾。例如：/my-app/。
   • 如果您的应用需要完全相对的路径（例如，部署在任意深度的子目录中，且不确定具体路径），您可以将 base 设置为 '' (空字符串) 或 ./。但请注意，这种方式在某些复杂场景下可能导致问题，并且可能需要额外的处理（如在服务器端配置重写规则）。对于大多数部署到固定子目录的场景，使用绝对路径更可靠。

2. 开发环境与生产环境：

   • base 配置主要影响 vite build 的输出。在开发模式（npm run dev）下，Vite 通常会忽略 base 配置，因为它会在本地开发服务器上提供服务，路径通常是相对根目录的。
   • 如果您需要为开发环境也指定一个 base 路径，可以考虑使用环境变量或条件逻辑。

3. 动态基础路径：

   • 在某些情况下，您可能希望根据不同的部署环境（如测试环境、生产环境）使用不同的 base 路径。您可以通过环境变量来实现这一点：

   // vite.config.js
   import { defineConfig, loadEnv } from 'vite';
   
   export default defineConfig(({ mode }) => {
     // 根据当前模式加载 .env.[mode] 文件中的环境变量
     const env = loadEnv(mode, process.cwd(), '');
   
     return {
       base: env.VITE_APP_BASE_PATH || '/', // 从环境变量获取，如果未设置则默认为根路径
       // 其他 Vite 配置项...
     };
   });

   登录后复制

   然后，您可以在 .env.production 文件中定义 VITE_APP_BASE_PATH=/docs/reconstatus/。

4. CDN 部署：

   • 如果您的静态资源部署在 CDN 上，base 也可以指向 CDN 的完整 URL，例如 base: 'https://cdn.example.com/my-app/'。

总结

正确配置 Vite 的 base 选项是解决应用部署到非根目录子路径时资源加载问题的关键。无论是通过命令行参数进行临时设置，还是在 vite.config.js 中进行持久化配置，理解其作用和正确的路径格式都至关重要。通过遵循本文提供的指南和最佳实践，您可以确保您的 Vite 应用在各种部署环境下都能稳定、高效地运行，避免因路径问题导致的 404 错误。

以上就是配置 Vite 构建输出的公共基础路径的详细内容，更多请关注php中文网其它相关文章！