已解决：Qt封装React应用windeployqt部署后单条字符串不显示问题

核心场景说明 #

封装在Qt客户端内的React应用，新增功能后已完成以下操作：

• 所有新增资源已加入resources.qrc配置，资源配置已刷新
• Qt本地构建运行全功能正常，无文本缺失问题
• 使用命令执行部署：windeployqt.exe "C:\builtProgramLocation\builtBprogamName.exe"
• 部署后仅单条新增字符串无法显示，其余同期新增的文本、功能均正常
• 清空构建目录、部署目录后全流程重走，问题仍复现

容易遗漏的排查方向 #

• 不要反复验证资源配置问题：单条文本缺失、其余同期新增内容全部正常的场景下，基本可以排除qrc漏配、资源没打包、路径错误这类共性问题，不用反复清理构建、重刷qrc浪费时间。
• 优先验证Web渲染内核的环境差异：Qt本地开发运行时调用的是本地安装的完整Qt环境下的WebEngine渲染库，windeployqt默认部署的发布版WebEngine组件，和本地调试版的CSS容错率、支持特性存在细微差异：比如对overflow: hidden裁切阈值、transform小数偏移、webkit前缀属性、行高/字体大小计算规则的解析不一致，很容易出现单块文本被挤出可视区域、被其他元素遮挡、和背景同色等问题，肉眼看起来就是“文本没加载”，实际文本节点已经存在。
• 开启WebEngine远程调试直接定位：不要靠界面表现猜原因，在Qt启动代码中加qputenv("QTWEBENGINE_REMOTE_DEBUGGING", "9222");，运行部署后的程序，在Chrome打开http://localhost:9222即可直接调试内嵌页面，10秒就能确认文本节点是否存在于DOM中：如果节点存在直接查计算后样式，如果节点不存在再查资源加载、JS运行报错。
• 排查字体 fallback 差异：本地开发环境系统预装了各类字体，windeployqt不会自动打包代码中引用的第三方字体，如果这条无法显示的文本刚好命中了未打包的特殊字体、且字体 fallback 规则配置不全，会出现文字渲染尺寸异常撑破容器被裁切、特殊字符渲染空白的问题，其余使用系统默认字体的文本则完全正常。
• 检查windeployqt参数遗漏：如果用Qt WebEngine承载React页面，执行部署时需要追加--webengine参数，否则会缺失WebEngine相关的渲染依赖，部分CSS特性会直接失效，刚好影响单条文本的渲染表现。
• 排查路径大小写敏感问题：Windows本地运行时路径大小写不敏感，windeployqt部署后qrc资源路径是大小写敏感的，如果这条文本关联的CSS文件、背景图、伪元素资源的路径写的大小写和qrc内配置不一致，会导致样式加载失败引发布局错位。

本次问题最终根因 #

问题根源为单条CSS规则适配异常：该规则在Qt本地构建运行的Web环境下可正常生效，windeployqt部署后的Web运行环境因渲染依赖的配置/版本差异，无法正常解析该CSS规则，导致文本偏移到可视区域外，修复该CSS规则后文本即可正常显示在预期位置。

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