laravel 12 默认深度集成 vite，核心原则是所有需哈希和版本控制的资源必须从 resources/ 目录导入，不可直放 public/ 下硬引用；@vite 指令仅识别以 resources/ 开头的绝对路径，图片等静态资源须通过 import 或 css url() 导入才能被 vite 处理并生成带哈希的路径，public/ 仅用于存放 favicon.ico 等无需构建的文件，生产环境严格依赖 public/build/manifest.json 进行路径映射。
Laravel 12 默认深度集成 Vite，静态资源路径配置的核心原则是：**所有需哈希、压缩、版本控制的资源必须从 resources/ 目录导入，不能直接放 public/ 下硬引用**。否则构建后路径断裂、缓存失效、CDN 更新不及时等问题会集中爆发。
入口资源必须用 resources/ 开头的绝对路径
@vite 指令只识别以 resources/ 为根的路径，且不接受相对写法（如 ./resources/js/app.js）或别名（如 @/js/app.js）。它依赖 laravel-vite-plugin 扫描这些路径生成 manifest 映射。
- ✅ 正确：
@vite(['resources/js/app.js', 'resources/css/app.css']) - ❌ 错误：
@vite('./resources/js/app.js')（报 Array to string conversion） - ❌ 错误：
@vite(['public/js/app.js'])（插件跳过处理，生产环境直接 404）
图片、字体等静态文件要“导入”而非“直链”
Vite 只会对被 JS 或 CSS 显式 import 的资源做哈希、复制、重命名。放在 public/ 下的文件虽可访问，但绕过构建流程，无法自动更新 CDN 缓存。
- 把 logo.png 放进
resources/images/，然后在 CSS 中写：background: url('../images/logo.png');→ 构建后自动转成/build/assets/logo.a1b2c3d4.png - 在 Vue 组件中：
<img :src="logo">，配合import logo from '@/images/logo.png'（注意：@ 别名需同步配tsconfig.json） - 不要在 Blade 里写：
<img src="/images/logo.png">—— 这个路径永远不变，上线后用户可能看到旧图
public/ 目录只放真正“无需构建”的文件
public/ 是 Web 服务器直接暴露的根目录，适合放那些不需要任何处理的资源：
- favicon.ico、robots.txt、sitemap.xml
- 第三方静态库（如 legacy.js），你明确不想让它参与打包
- 上传后的用户文件（通过 Storage 链接访问）
⚠️ 注意：/public/static/ 这类子目录里的文件，在 Vite 构建时会被原样复制到 public/build/static/，但不会加哈希、不进 manifest，所以仍不适合用于需要版本控制的业务资源。
manifest.json 必须存在且路径固定
Laravel 12 的 @vite 在生产环境完全依赖 public/build/manifest.json 做路径映射。这个路径是硬编码的，不能改。
- 运行
npx vite build后，必须检查public/build/manifest.json是否生成且 JSON 格式合法 - vite.config.js 中
build.outDir必须设为'public/build'（laravel-vite-plugin 会强制覆盖，但显式声明更稳妥） - 若用了自定义输出目录（如
public/assets），@vite指令将完全失效，除非重写 Blade 指令逻辑
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
