已发布Word加载项跨平台运行时settings.get返回null问题

触发失效的核心机制 #

• 长期以来Office对文档内webextension配置的匹配逻辑，仅以加载项的唯一id作为关联键，这也是多数开发者此前的普遍认知。
• 近期Office客户端的静默版本更新中，官方未公开同步调整了匹配校验逻辑：加载项与webextension配置的关联，不再仅校验id字段，而是会同时校验id、version、storeType、store四个字段的完整匹配组合。
• 这一规则变更没有对应的公开通知，且仅在近一周的推送版本中生效，和加载项上线3年仅最近一周出现同类异常的现象完全吻合。

两类webextension配置的匹配差异 #

• 无法被识别的旧版webextension1.xml中，主we:reference节点的store值为en-US，备用引用节点的store字段错写为加载项的id1234值，整体字段组合和新版客户端拉取到的加载项清单元数据不匹配。
• 可被正常识别的webextension2.xml中，主节点与备用引用节点的store值统一为en-001，和新版客户端当前获取到的加载项清单中的store字段值完全一致，因此可以完成关联识别。

异常触发的完整链路 #

1. 旧版本Office客户端保存文档时，会按照当时的校验规则，将客户端从Office商店拉取到的加载项store值（即en-US）写入对应webextension配置文件，同时将调用Office.context.document.settings.set存储的键值对保存在这份配置中，当时跨同版本设备访问时可以正常读取。
2. 新版Office客户端调整了商店区域编码的映射逻辑，同一发布在OMEX商店的加载项，客户端拉取清单时返回的store字段值从原有的固定en-US，变更为按客户端所在区域动态匹配的en-001编码。
3. 新版客户端打开旧文档时，按升级后的规则逐字段校验所有webextension配置的属性，发现旧配置中存储的store值和当前加载项清单的对应值不一致，就判定这份配置不属于当前加载项，不会关联其内部存储的settings键值对。
4. 因为没有找到匹配的已有webextension配置，Office会自动生成新的webextension2.xml，用当前版本识别到的新store值写入配置属性。此时通过Office.context.document.settings.get读取数据时，实际访问的是这份全新生成的空配置，自然会返回null。

可落地的临时规避方案 #

• 调整加载项清单配置，在AlternateReferences节点中补充覆盖历史版本所有store字段值的备用引用条目，让不同版本的客户端都能完成配置匹配。
• 加载项启动时增加兼容逻辑：当检测到settings.get返回预期外的null值时，遍历文档内所有同加载项id的webextension配置节点，提取旧配置中存储的键值对，迁移写入新生成的配置后再调用Office.context.document.settings.saveAsync完成持久化。

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