Webpack Encore不是Webpack简化版，而是Symfony官方封装的强约定构建层；直接修改webpack.config.js会绕过校验逻辑，导致isProduction()失效、runtime chunk丢失或public path错乱，必须通过Encore链式调用配置，导出仅限Encore.getWebpackConfig()。
Webpack Encore 不是 Webpack 的简化版，而是 Symfony 官方封装的、带强约定的构建层——直接改 webpack.config.js 很可能绕过 Encore 的校验逻辑，导致 Encore.isProduction() 失效、runtime chunk 丢失或 public path 错乱。
为什么 Encore.getWebpackConfig() 必须作为导出终点
Encore 内部依赖 lib/config-generator.js 对配置做二次注入（比如自动添加 DefinePlugin、修正 output.publicPath、插入 HtmlWebpackPlugin 实例）。如果你在 module.exports 前手动 merge 或覆盖配置对象，会跳过这些关键步骤。
- 常见错误：写成
module.exports = {...Encore.getWebpackConfig(), devtool: 'source-map'}—— 这会让enableSourceMaps()的条件判断失效 - 正确做法：所有定制必须通过
Encore.链式调用完成；如需底层修改，用Encore.configureWebpack()回调 - 例外场景：仅当你要注入非标准插件（如
CompressionPlugin）且确认不干扰 Encore 生命周期时，才用configureWebpack()
enableVueLoader() 和 enableReactPreset() 的 loader vs preset 区别
Vue 和 React 的集成方式本质不同：enableVueLoader() 只注册 vue-loader，不处理 JSX/Babel；而 enableReactPreset() 是一整套 Babel preset + @babel/preset-react + 自动启用 jsx 支持。
- 用 Vue？必须额外调用
Encore.enableTypeScriptLoader()或Encore.enableBabelTypeScriptPreset()才能解析.vue中的<script lang="ts"> - 用 React？若项目已存在
.babelrc，enableReactPreset()会静默覆盖它——建议删掉原有 Babel 配置，全权交给 Encore 管理 - 两者都禁用
enableSingleRuntimeChunk()会导致 HMR 失败，因为 Vue/React 的热更新依赖 runtime chunk 存在
addEntry() 的路径必须相对于 assets/ 目录
Encore 默认把 assets/ 当作源码根目录，无论你实际把 JS 放在哪，addEntry('app', './js/app.js') 中的 ./js/app.js 是从 assets/ 开始解析的，不是从 webpack.config.js 所在位置。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
立即学习“前端免费学习笔记（深入）”；
- 错误示例：
addEntry('app', '../src/js/app.js')→ 报错Cannot resolve './src/js/app.js' in assets/ - 正确结构：确保文件在
assets/js/app.js，然后写addEntry('app', './js/app.js') - 多入口时注意：每个 entry 的输出名（第一个参数）会成为最终生成的
build/app.js文件名，不能含斜杠或特殊字符
Encore.isProduction() 在 CLI 和 Node.js 环境下行为不一致
这个函数只读取 process.env.NODE_ENV，但 Symfony 的 bin/console 命令默认不继承 shell 的环境变量，导致 Encore.isProduction() 在 php bin/console encore:dev-server 中始终返回 false。
- 验证方法：在
webpack.config.js里加console.log(process.env.NODE_ENV)，运行npm run dev和php bin/console encore:dev-server对比输出 - 修复方式：启动命令前显式设置，例如
NODE_ENV=production php bin/console encore:build - 更稳妥的做法：不要依赖
Encore.isProduction()控制关键行为（如 CDN 路径），改用Encore.isSplitChunksEnabled()或硬编码环境标志
最常被忽略的是 Encore.cleanupOutputBeforeBuild() —— 它只在 CLI 模式下生效（npm run build），但在 php bin/console encore:build 中默认不触发，旧文件残留可能导致缓存错乱。如果用 Symfony 命令驱动构建，务必手动加 --clean 参数。
