如何在Symfony 4.4项目中升级Webpack Encore相关依赖包？

升级前准备 #

• 提交当前所有代码变更到版本库，确保可随时回滚到升级前状态
• 备份三个核心文件：webpack.config.js、assets/ 全目录、config/packages/webpack_encore.yaml
• 执行 composer show symfony/webpack-encore-pack 查看当前pack版本，记录关联依赖的版本号
• 执行 yarn list 或 npm list 查看前端依赖 @symfony/webpack-encore 的版本号，避免前后端依赖版本不兼容

升级操作步骤 #

• 第一步移除旧pack包：执行 composer remove symfony/webpack-encore-pack，不要加--no-scripts参数，确保Symfony Flex自动清理旧配置条目
• 第二步安装新bundle：Symfony 4.4仅兼容1.x版本的encore bundle，执行 composer require symfony/webpack-encore-bundle:^1.13 即可，禁止安装2.0及以上版本
• 第三步迁移配置：Flex会自动生成新的webpack_encore.yaml配置，对比备份的旧配置，将自定义配置项（如输出路径、public路径、dev server配置等）迁移到新配置，删除旧冗余配置；如果Flex未自动生成配置，手动创建对应文件填入基础配置即可
• 第四步升级前端依赖：执行 yarn upgrade @symfony/webpack-encore@^1.0 --dev（npm对应命令为npm install @symfony/webpack-encore@^1.0 --save-dev），确保前端encore版本和后端bundle大版本匹配
• 第五步校验webpack配置：对比备份的webpack.config.js和新bundle的默认示例配置，替换废弃API，比如旧的createSharedEntry需替换为addEntry+splitEntryChunks()，enableSassLoader等方法的入参有调整也要同步修改
• 第六步功能验证：先执行yarn dev测试开发环境编译是否报错，再执行yarn build测试生产环境编译是否正常，最后启动Symfony服务访问页面前端，确认资源加载正常、无JS/CSS报错

依赖相关注意事项 #

• symfony/webpack-encore-bundle 不再默认依赖symfony/asset组件，如果项目之前依赖pack附带的asset组件，需要单独执行composer require symfony/asset安装，否则会出现asset()函数不存在的报错
• 2.0及以上版本的symfony/webpack-encore-bundle最低要求Symfony 5.4，强制安装会出现核心依赖冲突
• 如果项目用了Encore的生态插件（如encore-react、encore-vue），需要同步升级这些插件到和1.x版本Encore兼容的版本，避免编译报错
• 升级后如果出现manifest.json找不到的报错，检查新配置里的output_path参数是否和实际编译产物的输出路径一致

升级风险规避方案 #

• 所有升级操作先在本地开发环境完成全流程测试，确认所有功能正常后再部署到测试环境、生产环境
• 出现Composer依赖冲突时，执行composer why-not symfony/webpack-encore-bundle 1.13查看冲突的依赖包，优先升级兼容的小版本即可，不要盲目升级Symfony核心组件导致其他功能异常
• 编译出现报错时，先把webpack.config.js恢复到默认配置，逐步添加自定义配置项定位问题，不要直接修改bundle的核心源码
• 生产环境部署前，先清理旧的编译产物rm -rf public/build/*，再重新执行生产环境编译，避免旧缓存文件导致资源加载异常

内容的提问来源于stack exchange，提问作者alinrj