如何在宝塔面板配置Vite项目生产环境_解决路径映射与静态资源加载-php教程-PHP中文网

laravel的@vite在宝塔部署后404，因生产环境未正确读取public/build/manifest.json，导致生成原始路径script标签，而vite构建文件带hash，nginx无法匹配；需确保manifest存在、app_url完整、@vite传入build参数、vite.config.js启用manifest并设outdir为public/build，且nginx放行/build/路径。

如何在宝塔面板配置vite项目生产环境_解决路径映射与静态资源加载

为什么 @vite 指令在宝塔部署后加载 404

因为 Laravel 的 @vite 默认不读 public/build/manifest.json，生产环境仍按原始路径（如 resources/js/app.js）生成 script 标签，而 Vite 构建后真实文件名是带 hash 的（如 /build/assets/app.a1b2c3d4.js），Nginx 找不到就返回 404。

宝塔本身不干预这个逻辑——它只托管静态文件，不会帮你解析 manifest 或重写 HTML 中的资源路径。问题根子在 Laravel + Vite 的集成配置没对齐。

确认 vite build 后 public/build/manifest.json 文件存在且 JSON 合法
APP_URL 必须设为完整协议+域名（如 https://your-site.com），否则 manifest 中路径拼接会出错
Blade 中调用 @vite 时必须传第二个参数，比如 @vite(['resources/js/app.js'], 'build')，否则 Laravel 不知道去哪个子目录找 manifest

vite.config.js 必须显式启用 manifest 并固定 outDir

默认 build.manifest 是 false，Vite 就不会生成 manifest.json；outDir 若不是 'public/build'，Laravel 就找不到文件。

直接改 vite.config.js：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

export default defineConfig({
  build: {
    outDir: 'public/build',
    manifest: true,
  },
})

不要用相对路径如 ../public/build，Vite 会报错或输出到错误位置
若项目有多个入口（如后台/前台分离），每个 @vite([...]) 调用中列出的源路径（如 resources/js/admin.js）必须和 manifest 中的 key 完全一致，包括大小写和斜杠方向
CSS 文件也要显式列进 @vite 数组，哪怕它被 JS import，否则不会出现在 manifest 里

宝塔 Nginx 配置要允许 /build/ 下所有静态文件直出

宝塔默认的网站配置通常没问题，但若你手动改过 root 或加了 rewrite，可能拦截了 /build/ 路径下的请求。

进宝塔 → 网站 → 设置 → 配置文件，检查有没有类似这样的规则：

location / {
  try_files $uri $uri/ /index.php?$query_string;
}

这条规则本身没错，但必须确保它不覆盖 /build/ 子路径——Vite 输出的 /build/assets/xxx.js 是真实物理文件，应由 Nginx 直接返回，而不是丢给 PHP 处理
如果加了自定义 rewrite（比如把所有请求都转给 index.php），需在前面加一条放行：location ^~ /build/ { }
确认宝塔「静态文件缓存」已开启，它会自动加 expires 指令，对带 hash 的文件很友好；但若看到 Cache-Control: no-cache，大概率是 PHP 脚本自己输出了冲突头，得查 Laravel 中间件或 Blade 里的 header() 调用

常见部署后空白页的快速定位步骤

不是代码错了，而是路径断了。打开浏览器 DevTools → Network 标签页，刷新页面，看哪些资源返回 404：

如果 /build/manifest.json 404：说明 vite build 没成功，或没传到服务器对应位置
如果 /build/assets/app.xxxx.js 404，但 /build/manifest.json 正常：检查 @vite 第二个参数是否漏写、APP_URL 是否少写 https://、manifest 里 key 是否多写了 /（比如写成 /resources/js/app.js 而不是 resources/js/app.js）
如果 CSS 加载了但 JS 报错：检查 public/build/ 下是否有 assets/ 子目录，以及该目录权限是否为 755（宝塔上传有时会变成 644）

manifest 映射依赖字符串完全匹配，连一个点、一个空格都不能错——这是最容易被忽略的硬性约束。