npm run dev-server 启动后页面空白或报 Cannot find module 'vue'，根本原因是 Encore 的 enableVueLoader() 不自动安装依赖，需手动安装 vue、vue-loader 及 @vue/compiler-sfc（Vue 3）并确保版本匹配，同时检查 app.js 入口使用 createApp、enableVueLoader() 调用顺序及 TypeScript 配置。
Webpack Encore 不是 Webpack 的替代品，而是它的“配置简化层”——你不需要手动写 webpack.config.js 里的 loader 规则、plugin 列表或 resolve 配置，Encore 已经为你预设了合理默认值。但这也意味着：一旦你脱离它封装的 API（比如直接改 webpack.config.js 原生配置），就容易和 Encore 的内部逻辑冲突，导致构建失败或热更新失效。
为什么 npm run dev-server 启动后页面空白或报 Cannot find module 'vue'
这是 Vue 集成最常卡住的第一步。Encore 的 enableVueLoader() 只负责启用 vue-loader，但不自动安装 Vue 相关依赖。
- 必须显式安装
vue、vue-loader和vue-template-compiler（注意版本匹配：Vue 3 对应vue-loader@^17，vue-template-compiler已废弃，改用@vue/compiler-sfc） -
assets/js/app.js中需正确创建应用实例：createApp（Vue 3）而非new Vue（Vue 2） - 检查
webpack.config.js中enableVueLoader()是否在addEntry()之后调用——顺序错会导致入口文件不被处理 - 若使用 TypeScript，还需额外安装
typescript和@vue/runtime-dom，并在enableVueLoader()中传入{ ts: true }
Encore.isProduction() 怎么影响实际输出文件
这个布尔值不只是用来开关压缩，它会联动触发一整套构建行为切换：
- 开发模式（
false）：生成未压缩的 JS/CSS，保留 source map，启用 HMR（热模块替换），输出路径为public/build/但不加哈希后缀 - 生产模式（
true）：自动启用TerserPlugin压缩 JS、CssMinimizerPlugin压缩 CSS，文件名追加内容哈希（如app.abc123.js），同时禁用 source map（除非显式调用enableSourceMaps(true)） - 关键细节：
enableVersioning(Encore.isProduction())控制是否启用文件哈希，但哈希只作用于output.filename和output.chunkFilename，不会影响public/build/下的 manifest.json 生成逻辑
如何让 Encore 打包后的 CSS 正确加载到 Symfony 模板中
Symfony 的 asset() 函数默认读取的是 public/ 下的静态文件，而 Encore 输出在 public/build/。这中间需要两层对齐：
立即学习“前端免费学习笔记（深入）”；
- 确保
webpack.config.js中setOutputPath('public/build/')和setPublicPath('/build')保持一致，后者决定了浏览器请求资源时的 URL 前缀 - 模板中必须用
{{ asset('build/app.css') }}，不能写成/build/app.css硬编码——否则在子目录部署时路径会断 - 如果启用了
enableVersioning()，CSS 文件名带哈希，此时必须配合manifest.json使用；但 Symfony 默认不读该文件，需手动在 Twig 中解析或使用symfony/webpack-encore-bundle提供的encore_entry_link_tags()辅助函数 - 注意：CSS 中的字体、图片等相对路径，会被 Webpack 自动重写为
/build/xxx，前提是这些资源通过require('./fonts/icon.woff')方式被 JS 或 CSS 显式引用
真正容易被忽略的是缓存穿透问题：生产环境开启 versioning 后，旧的 app.css 文件仍留在 public/build/ 目录下，但 HTML 引用的是新哈希名。如果没配好服务器缓存策略（比如 Nginx 对 /build/* 设置了长期缓存），用户可能拿到过期的 HTML 却请求新的 CSS，导致样式错乱。清理 public/build/ 目录本身不是必须的，但 CI 流程中最好加上 rm -rf public/build/* 再运行 npm run build，避免残留文件干扰。
