css不生效的根本原因是vite依赖js入口导入资源，必须在resources/js/app.js中显式import '../css/app.css'，@vite不能直接传入css路径；@vite参数须为resources/开头的数组且置于blade顶层；public/build目录需存在且含manifest.json和assets文件。
刚升级 Laravel 11 的新手常发现 CSS 不生效、页面空白或控制台报 404，根本不是代码写错，而是 Vite 构建链里某一个环节没对上——比如 CSS 没被 JS 入口 import、@vite 写法错、public/build 目录压根没生成。
确认 CSS 是由 JS 入口主动引入的
这一步最容易被忽略：Vite 不会自动打包 resources/css/app.css，它只认 JS 入口文件（如 resources/js/app.js）里显式 import 的资源。【CSS 文件必须在 JS 中 import，不能靠 @vite 直接传入】
打开 resources/js/app.js，确保第一行或靠前位置有：
import '../css/app.css';
如果删掉了这行，哪怕 @vite(['resources/js/app.js', 'resources/css/app.css']) 写得再全，CSS 也不会进构建产物——因为 Vite 的依赖图是从 JS 入口开始爬的，不 import 就等于“看不见”。
别信网上抄来的“直接把 CSS 路径塞进 @vite 数组就行”，那是 Mix 思维，Vite 不吃这套。
Blade 中 @vite 指令必须严格按数组写
@vite 不是万能加载器，它只负责注入脚本和样式链接，且语法极其敏感。
第一步：确保 @vite 出现在
里，且不在任何 @if、@section 或 @push 块内部——Blade 编译阶段就解析它，嵌套会导致指令失效。第二步：参数必须是数组，路径必须以 resources/ 开头：
@vite(['resources/js/app.js']) ✅
@vite('resources/js/app.js') ❌（触发 Array to string conversion 错误）
@vite(['./resources/js/app.js']) ❌（带 ./ 会导致 laravel-vite-plugin 找不到入口）
第三步：不要单独传 CSS 路径。@vite(['resources/js/app.js', 'resources/css/app.css']) 看似合理，但 Vite 会尝试把 CSS 当作独立入口处理，而 Laravel 插件根本不支持这种用法——最终要么报错，要么静默忽略 CSS。
检查 public/build 是否真实存在且非空
开发时 npm run dev 运行着，页面能热更新；但一执行 npm run build，刷新页面就空白或样式丢失？大概率是 public/build 目录压根没生成，或者里面只有 .gitkeep 没有实际文件。
运行 npm run build 后，立刻检查项目根目录下 public/build 是否存在，且至少包含 assets/ 子目录和 manifest.json 文件。
如果目录不存在，说明 vite build 没跑成功——常见原因是 vite.config.js 里漏了 laravel() 插件，或插件顺序错了（比如放在 vue() 之后）。
如果目录存在但为空，十有八九是 vite.config.js 的 build.outDir 被手动改过，而 laravel-vite-plugin 仍坚持往 public/build 写，结果写到了别的地方却没人发现。
Tailwind 或 Swiper 的 CSS 必须走 Sass @import，不能 JS import
方法一：Tailwind CSS
在 resources/sass/app.scss 顶部，按顺序写：
@tailwind base;
@tailwind components;
@tailwind utilities;
然后确保 resources/js/app.js 里 import 了这个 app.scss，而不是单独 import 'tailwindcss/tailwind.css'——后者会让 Vite 输出额外 CSS 文件，破坏单文件结构，还可能因加载顺序导致样式被覆盖。
方法二：Swiper 样式
不能写 import 'swiper/css'，否则 Vite 会生成 assets/swiper.xxxxx.css 独立文件，而且容易报 Missing "./swiper" specifier 错误。
正确做法：在 resources/sass/_swiper.scss 里用完整相对路径导入：
@import '../../../node_modules/swiper/swiper.scss';
@import '../../../node_modules/swiper/modules/navigation.scss';
@import '../../../node_modules/swiper/modules/pagination.scss';
再在 app.scss 里 @import 'swiper'; ——这样 Swiper 样式就彻底编译进主 CSS，不再多出一个文件。
【删掉所有 JS 文件里的 swiper/css import 行，否则白干】
验证开发服务器是否真在跑
打开浏览器开发者工具 → Network 标签页，刷新页面，看 JS/CSS 请求是走 http://localhost:5173 还是 /build/xxx.js。
如果看到的是 /build/xxx.js，说明 Vite 开发服务器根本没启动，或者 NODE_ENV 被设成了 production —— 此时 @vite 会 fallback 到 public/build，但你刚 npm run dev，public/build 还没生成，自然 404。
确认终端里正在运行 npm run dev，且输出里有 “Local: http://localhost:5173/” 字样；如果显示 “0.0.0.0:5173”，立刻停掉，改 vite.config.js 的 server.host 为 'localhost' 或 true，再重跑。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
