Laravel Mix 路径与部署关键点：mix.js() 和 mix.postCss() 的源路径须基于项目根目录（勿用 ./ 或绝对路径），输出目录必须在 public/ 下；manifest 文件仅在 production 模式生成且必须随静态文件部署，否则 mix() 辅助函数失效；setPublicPath() 后需同步更新 Web 服务器配置。
直接上手就能跑通，但 90% 的人卡在路径、输出位置和部署环节。Laravel Mix 不是黑盒，它只是 webpack 的一层封装，关键在于理解 mix.js() 和 mix.postCss() 这两个调用背后的真实路径约束与运行时机。
mix.js() 和 mix.postCss() 的路径必须写对
这两个方法的第一个参数是源文件路径，第二个是输出目录（不是完整文件名），且都必须基于项目根目录的相对路径 —— 不能用 ./ 开头，也不能用绝对路径。
-
mix.js('resources/js/app.js', 'public/js')✅ 正确：源文件存在，输出目录为public/js/ -
mix.js('js/app.js', 'js/')❌ 错误：源路径找不到，输出目录没落在public/下，Blade 中<script src="/js/app.js">会 404 -
mix.postCss('resources/css/app.css', 'public/css', [...])✅ 支持 PostCSS 插件链，比如tailwindcss必须放在这里加载，不能只靠@tailwind指令
开发时正常、上线后全部 404 的原因
最常见就是 mix-manifest.json 没生成或没传上去，而 Blade 中用了 {{ mix('js/app.js') }} 这个指令依赖它。
- 没运行
npm run production：开发用npm run dev不生成 manifest，只有production模式才写入public/mix-manifest.json - CI/CD 漏传
public/mix-manifest.json：这个文件不在.gitignore里，但很多部署脚本默认跳过public/下非源码文件 -
mix.setPublicPath('dist')后没同步改 Nginx 配置：Blade 仍按/js/app.js请求，但文件实际输出到了dist/js/app.js，Nginx 找不到
条件编译模块 JS 时别硬编码路径
多个功能模块共存时，想按需开启编译，不要在 webpack.mix.js 里写一堆 if (process.env.MODULE1 === 'true') {...}，Node.js 原生支持 JSON 加载，更干净。
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
立即学习“前端免费学习笔记（深入）”；
- 在项目根目录放
module_statuses.json：{ "analytics": true, "chat": false } - 在
webpack.mix.js中：const status = require('./module_statuses.json'); - 然后：
if (status.analytics) { mix.js('Modules/Analytics/js/index.js', 'public/js'); } - ⚠️ 注意：
require()自动解析 JSON，但文件名不能以_或.开头，否则要改用fs.readFileSync+JSON.parse
不要用 mix.webpackConfig() 覆盖全部配置
很多人想加个 alias 或改 resolve 规则，就直接写 mix.webpackConfig({ resolve: { ... } })，这会把 Mix 内置的 @ 别名（指向 resources/js）、@/css 等全干掉。
- 需要扩展 alias 时，用
mix.webpackConfig({ resolve: { alias: { '@modules': path.resolve(__dirname, 'Modules') } } })，只追加，不覆盖 - 想改 loader？优先查 Mix 是否已有对应方法，比如
mix.options({ terser: { extractComments: false } })比手动配webpackConfig更安全 - 所有 Mix 方法（
.vue()、.react()、.version()）都建立在默认配置基础上，破坏它等于放弃 Mix 的便利性
真正麻烦的从来不是怎么写那一行 mix.js()，而是部署时 public 目录下少了一个 mix-manifest.json，或者 APP_URL 和 Nginx root 不一致导致路径错位。这些点不验证一遍，光跑通本地开发没用。
