首先确认 public/build/manifest.json 是否存在且内容合法；必须在 vite.config.ts 中设置 build.outdir='public/build' 和 manifest: true；blade 中 @vite 需传 'build' 参数且路径与 manifest key 完全一致；nginx 需添加 location ^~ /build/ { try_files $uri =404; } 放行规则；app_url 必须为完整 url，子路径部署还需配置 vite base。
public/build/manifest.json 不存在或路径不对
打包后 @vite 指令失效、页面空白或资源 404，第一件事是确认 public/build/manifest.json 是否真实存在且内容合法。Laravel 的 @vite 在生产环境完全依赖这个文件做路径映射——它不读源码路径，只查 manifest 里 key（如 "resources/js/app.js"）对应的带 hash 的产出路径。
常见错误包括：
-
vite.config.ts里没开build.manifest: true -
build.outDir被设成'dist'或'../public/build'等非标准值，导致 Laravel 找不到 manifest - 用了
laravel-vite-plugin却手动改了outDir，插件会忽略该配置，仍输出到默认的public/build
正确做法是：在 vite.config.ts 中显式固定输出位置并启用 manifest：
export default defineConfig({
build: {
outDir: 'public/build',
manifest: true,
}
})
执行 vite build 后，检查 public/build/manifest.json 是否生成，且内容类似 {"resources/js/app.js": {"file": "assets/app.a1b2c3d4.js"}}。
@vite 指令没传 build 目录参数
Laravel 默认只在开发环境注入 HMR 脚本；生产环境下，@vite 必须知道去哪找 manifest，否则它会退化为按原始路径（如 /resources/js/app.js）生成 script 标签，而该路径下根本没文件，Nginx 直接返回 404。
必须在 Blade 中显式传入第二个参数：'build'：
@vite(['resources/js/app.js'], 'build')
注意：
- 第一个参数数组里的路径，必须和
manifest.json中的 key 完全一致（大小写、斜杠方向、是否带resources/前缀） - CSS 文件如果没被 JS import，也得列进数组，否则不会出现在 manifest 里
- 不要写成
@vite(['js/app.js'])或@vite(['app.js'])，路径错一个字符就匹配失败
Nginx 拦截了 /build/ 下的真实文件请求
manifest 解析出来的路径形如 /build/assets/app.a1b2c3d4.js，这是 Nginx 应该直接返回的物理文件。但如果 Nginx 配置里只有全局 try_files $uri $uri/ /index.php?$query_string，且没有前置放行规则，请求就会被错误地转发给 PHP，而 index.php 显然不处理 /build/ 路径，最终 404。
宝塔或手动配置 Nginx 时，必须加一条明确放行：
location ^~ /build/ {
try_files $uri =404;
}
这条规则要放在 location / 之前，确保优先匹配。验证方式：直接浏览器访问 https://yoursite.com/build/assets/app.xxxx.js，应返回 JS 内容（200），而不是跳转或报错。
APP_URL 不完整导致 manifest 路径拼接出错
当 APP_URL 在 .env 中只写域名（如 APP_URL=myapp.test）或缺协议（如 APP_URL=https://myapp.test 缺少 https://），Vite 插件在生成 manifest 时可能把资源路径拼成相对地址或错误前缀，导致 @vite 解析出的 URL 不可访问。
务必保证 APP_URL 是完整 URL：
APP_URL=https://myapp.test
如果部署在子路径（如 https://myapp.test/admin），还需同步设置 vite.config.ts 中的 base：
export default defineConfig({
base: '/admin/',
// ...
})
此时 @vite 生成的 script src 会是 /admin/build/assets/app.xxxx.js，Nginx 需对应支持该前缀——但注意：base 和 APP_URL 是两回事，前者影响构建产物路径，后者影响 Laravel 辅助函数和 manifest 解析逻辑，漏掉任一都可能引发 404。
