必须用 npm run watch（Mix）或 npm run dev（Vite），因 dev/watch/build 语义不同：watch 持续监听编译，dev 在 Vite 中即热更新，在 Mix 中仅为单次构建，build 仅 Vite 专用且需 @vite 配合。
在 Laravel 项目中执行前端资源构建时，用错 npm 命令会导致 CSS 不更新、页面白屏、HMR 失效或生产环境样式错乱——这些都不是缓存问题，而是命令语义和输出路径完全不匹配造成的。
区分 dev/watch/build 的本质作用
npm run dev 编译一次，输出到 public/css（或 public/build），不监听文件变化，适合 CI 构建或快速验证单次结果。
npm run watch 持续监听 resources/assets/sass/ 或 resources/js/ 下的文件变动，自动重新编译并刷新浏览器（需配合 Laravel Mix 的 browserSync 或 Vite HMR），【开发时必须用这个，不是 dev】。
npm run build 是 Vite 专用命令，仅在使用 vite.config.js + laravel-vite-plugin 时有效；它会生成带哈希的文件名和 manifest.json，输出到 public/build；Laravel 的 @vite 指令依赖此结构，【mix 项目不能用 build，会报错】。
立即学习“前端免费学习笔记（深入）”；
判断当前项目用的是 Mix 还是 Vite
打开项目根目录的 package.json，检查 scripts 字段：
若含 "dev": "npm run development" 或 "dev": "mix" 或 "development": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js" → 属于 Laravel Mix 体系。
若含 "dev": "vite" 和 "build": "vite build"，且已安装 vite 和 laravel-vite-plugin → 属于 Vite 体系。
注意：Mix 和 Vite 不能混用。package.json 里同时存在 mix 和 vite 脚本，说明项目处于迁移中途，必须先统一工具链再执行任何构建命令。
正确执行构建命令的操作路径
第一步：确认 .env 中 APP_DEBUG=true 且 APP_ENV=local（Vite HMR 和 Mix 的 source map 依赖此）。
第二步：进入项目根目录，运行 npm install（确保 node_modules 完整，尤其 laravel-mix 或 vite 及其插件已安装）。
第三步：根据工具链选择对应命令：
→ Mix 项目：终端执行 npm run watch（不是 dev），等待出现 [webpack.Progress] 100% 和 Compiled successfully 消息；此时修改 app.scss，保存后几秒内浏览器自动刷新并应用新样式。
→ Vite 项目：终端执行 npm run dev（Vite 的 dev 就是 watch），确保终端显示 Local: http://localhost:5173 并保持运行；Blade 中 @vite(['resources/js/app.js']) 才能注入热更新脚本。
第四步：验证 public 目录输出：
• Mix 项目检查 public/css/app.css 是否更新时间戳；
• Vite 项目检查 public/build/ 下是否有 assets/ 子目录及 manifest.json 文件。
