Sulu 2.2媒体上传页加载后白屏 控制台报icon转换器未定义错误

问题触发原因 #

控制台抛出的list field transformer with the key "icon" is not defined错误，本质是前后端依赖版本不对齐导致的：

• Sulu 2.2 系列的小版本迭代中，在2.2.18版本的媒体模块表格配置里，新增了字段类型为icon的列配置
• 线上部署的生产环境前端静态资源，是基于更早的Sulu 2.2小版本构建的，全局的字段转换器注册表里没有提前注册icon类型对应的渲染逻辑
• 当前端加载到后端返回的、带icon字段的列表配置时，直接在注册表查找对应转换器失败抛出错误，MobX驱动的表格渲染流程被中断，最终出现页面短暂加载目录后直接白屏的现象
• 该问题和浏览器无关，因为是前端代码内部的逻辑报错，所以Chromium、Chrome、Firefox都会复现同样的问题。

具体修复操作 #

• 先核对实际安装的Sulu版本：在项目根目录执行composer show sulu/sulu，查看当前~2.2约束下实际拉取的版本号，确认是否自动升级到了引入icon字段配置的小版本
• 执行生产环境缓存清理与资源发布：
  • 清空应用运行缓存：php bin/console cache:clear --env=prod
  • 发布后端到公共目录的静态资源：php bin/console assets:install --env=prod
  • 基于当前安装的Sulu前端源码，重新构建生产环境的前端资源，不要复用旧版本遗留的构建产物
• 如果项目自定义过媒体模块的列表字段配置，检查自定义配置里是否新增了icon类型的列：如果当前Sulu版本本身不支持该字段类型，临时移除该列配置即可恢复页面加载
• 版本对齐兜底方案：如果重新构建资源后问题仍存在，可以通过Composer将Sulu版本临时锁定到与现有前端资源匹配的小版本（例如2.2.17），避免~2.2的浮动版本约束自动拉取不兼容的更新依赖，锁版本后执行composer update sulu/sulu --with-all-dependencies完成依赖对齐，再重复缓存清理、资源发布操作。

常见无效操作避坑 #

• 清除浏览器缓存、更换浏览器、隐身模式访问都无法解决问题：该报错是前端代码内部的组件依赖缺失，和浏览器环境无关联
• 不要手动修改前端注册表代码硬补icon转换器的空实现：这种临时修改会在下次Sulu版本更新时被覆盖，属于治标不治本的方案，从根源对齐前后端依赖版本才能稳定解决问题

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