Webpack Encore是Symfony官方封装的构建层，需通过链式API配置：设对.setOutputPath、setPublicPath、addEntry和enableVersioning四行；开发用npm run watch，Twig中必须用{{ asset() }}引用资源。
Webpack Encore 不是“配个 Webpack”，而是 Symfony 官方封装的构建层——直接改 webpack.config.js 里的 API 调用，就能控制输出、加载器、环境行为。硬套原生 Webpack 配置反而会破坏 Encore.getWebpackConfig() 的内部逻辑。
webpack.config.js 必须设对的四个配置项
很多构建失败或路径 404，根源就在这四行没对齐：
-
.setOutputPath('public/build/')：产物必须落进public/下，否则 Web 服务器无法直接提供静态文件 -
.setPublicPath('/build')：Twig 中{{ asset('js/app.js') }}拼出来的 URL 前缀，若部署在子目录（如/myapp/），得改成/myapp/build -
.addEntry('app', './assets/js/app.js')：入口名（如app）会成为输出文件前缀，app.js和app.css都由此生成 -
.enableVersioning(Encore.isProduction())：生产环境开启后，自动加哈希，但必须配合asset.yaml中的json_manifest_path: '%kernel.project_dir%/public/build/manifest.json'才能正确解析路径
开发时用 watch，别碰 dev-server
npm run watch 是默认开发流：监听变更、重编译、写入磁盘、支持 source map。它不启动 HTTP 服务，也不做 HMR（热模块替换）——这不是缺陷，是设计取舍。
常见误操作：
立即学习“前端免费学习笔记（深入）”；
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 手动运行
npx webpack serve或配encore dev-server：Encore 默认不兼容，容易和 Symfony 的symfony server:start端口冲突，且 Twig 引用的仍是/build/xxx.js，不是localhost:8080/xxx.js - 期望 CSS 改动后页面局部刷新：Encore 的 watch 不处理 HMR，要真需要，得额外加
.enableReactPreset()或插件，但绝大多数 Symfony 页面跳转场景下，F5 刷新更稳 - 把
watch当成长期后台进程跑在生产环境：它不压缩、不哈希、不分离 vendor，只适合本地开发
Twig 中引用资源必须走 {{ asset() }}，不能硬编码路径
即使你看到 public/build/app.js 文件存在，也不能在模板里写 <script src="/build/app.js"></script>。原因有三：
- 开发时没哈希，生产时有哈希：
app.a1b2c3.js→ 硬编码路径会 404 - CDN 或子目录部署时，
asset()会根据asset.yaml配置自动补前缀，硬写死就失效 - 使用
splitEntryChunks()后，会多出runtime.js、vendor.js等文件，asset()能从entrypoints.json自动读取全部依赖链，硬写只能手追
正确写法是：<script src="{{ asset('build/app.js') }}"></script>（注意路径含 build/ 前缀，这是 setPublicPath() 决定的）
第三方库（如 toastr、axios）导入失败的典型解法
报 ReferenceError: toastr is not defined 不是 Encore 问题，而是模块暴露方式和全局挂载不匹配：
- ESM 导入必须显式使用：
import * as toastr from 'toastr';，然后调用toastr.info()，不能依赖window.toastr - 想挂到全局？得用
.autoProvideVariables({ 'window.toastr': 'toastr' })，但前提是该库本身导出的是 UMD 格式；toastr4.x 后默认 ESM，所以更可靠的是在app.js顶部加window.toastr = require('toastr'); - CSS 透明？因为
toastr.min.css依赖字体和图标资源，需确保.copyFiles({ from: './node_modules/toastr/build/', to: 'toastr/[name].[ext]' })并在 JS 中 import 对应 CSS，否则字体路径 404 导致样式崩坏
真正容易被忽略的点：Webpack Encore 的所有 loader 和插件都通过 Encore. 链式调用启用，而不是往 module.exports 里塞原生 Webpack 配置——混用会导致部分功能静默失效，比如 enableVersioning() 依赖内部插件注册顺序，手动加 webpack-manifest-plugin 反而会冲突。
