当 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> 或 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 选项。这种方式将配置固化在项目代码中，易于版本控制和团队协作。
示例代码：
在您的 vite.config.js 文件中添加 base 属性：
// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
base: '/docs/reconstatus/', // 设置您的公共基础路径
// 其他 Vite 配置项...
});
说明：
- defineConfig 辅助函数有助于智能提示和类型检查。
- base 属性的值应与您应用实际部署的子目录路径一致。
注意事项与最佳实践
-
路径格式：
- base 值通常是一个以 / 开头的绝对路径（相对于域名根目录），并建议以 / 结尾。例如：/my-app/。
- 如果您的应用需要完全相对的路径（例如，部署在任意深度的子目录中，且不确定具体路径），您可以将 base 设置为 '' (空字符串) 或 ./。但请注意，这种方式在某些复杂场景下可能导致问题，并且可能需要额外的处理（如在服务器端配置重写规则）。对于大多数部署到固定子目录的场景，使用绝对路径更可靠。
-
开发环境与生产环境：
- base 配置主要影响 vite build 的输出。在开发模式（npm run dev）下，Vite 通常会忽略 base 配置，因为它会在本地开发服务器上提供服务，路径通常是相对根目录的。
- 如果您需要为开发环境也指定一个 base 路径，可以考虑使用环境变量或条件逻辑。
-
动态基础路径：
- 在某些情况下，您可能希望根据不同的部署环境（如测试环境、生产环境）使用不同的 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/。
-
CDN 部署：
- 如果您的静态资源部署在 CDN 上，base 也可以指向 CDN 的完整 URL，例如 base: 'https://cdn.example.com/my-app/'。
总结
正确配置 Vite 的 base 选项是解决应用部署到非根目录子路径时资源加载问题的关键。无论是通过命令行参数进行临时设置，还是在 vite.config.js 中进行持久化配置，理解其作用和正确的路径格式都至关重要。通过遵循本文提供的指南和最佳实践，您可以确保您的 Vite 应用在各种部署环境下都能稳定、高效地运行，避免因路径问题导致的 404 错误。
