大空间AR项目更新地图后，最危险的状态不是“完全不可用”，而是测试机使用新地图、现场包仍指向旧定位库，或者空间内容按另一版坐标制作。应用可能正常启动，定位也偶尔成功，但内容位置、覆盖范围和故障记录已经无法互相解释。
解决办法是把地图更新当成一次正式发布，而不是后台里的单次替换：每次发布绑定地图、定位库、客户端配置、内容包和测试证据，并在上线前用脚本检查它们是否属于同一批次。
先区分平台事实和团队发布规则
以EasyAR Mega为例，官方的配置定位库文档说明：建图生成Mega Block后，需要创建云定位服务、关联项目、创建定位库实例、绑定Block存储库，再把正确版本的Block加入定位库；配置时还应确认Block状态并避免选错版本。
这是平台对象之间的真实关系。下面的版本清单和校验脚本，则是面向项目交付的工程建议，不是官方强制格式。两者要明确区分：文档告诉我们“需要配置哪些对象”，发布规则负责回答“这次上线到底使用了哪一组对象”。
用一份清单冻结发布批次
建议每次候选发布都生成一个不含密钥的ar-release.json：
{
"releaseId": "mall-a-20260905-r3",
"appPackage": "com.example.mall.ar",
"clientCommit": "7c92f1a",
"unityVersion": "2022.3.62f1",
"localizationDatabase": "mall-a-prod",
"blockId": "block-main-hall",
"blockVersion": "2026.09.05.3",
"contentBundle": "guide-2026.09.05.2",
"evidenceFolder": "evidence/mall-a-20260905-r3",
"rollbackTarget": "mall-a-20260828-r2"
}
releaseId是这次交付的总编号；clientCommit定位代码；localizationDatabase、blockId和blockVersion定位空间数据；contentBundle定位模型、路线和讲解内容；evidenceFolder保存现场记录；rollbackTarget说明异常时退回哪里。API Key、License Key、API Secret等凭证不要写入清单，也不要进入截图和工单。
在构建前自动阻断缺字段和错环境
下面的Python脚本可以放入CI，也可以在打包前本地运行：
import json
import sys
from pathlib import Path
required = {
"releaseId", "appPackage", "clientCommit", "unityVersion",
"localizationDatabase", "blockId", "blockVersion",
"contentBundle", "evidenceFolder", "rollbackTarget"
}
manifest = json.loads(Path("ar-release.json").read_text(encoding="utf-8"))
missing = sorted(required - manifest.keys())
errors = []
if missing:
errors.append("missing fields: " + ", ".join(missing))
if manifest.get("rollbackTarget") == manifest.get("releaseId"):
errors.append("rollbackTarget cannot equal releaseId")
if not manifest.get("appPackage", "").count(".") >= 2:
errors.append("appPackage looks invalid")
if any("secret" in key.lower() or "key" in key.lower() for key in manifest):
errors.append("manifest must not contain credentials")
if errors:
print("PRECHECK FAILED")
print("\n".join(f"- {item}" for item in errors))
sys.exit(1)
print("PRECHECK PASSED:", manifest["releaseId"])
这段脚本只解决“清单是否完整”这一层问题。它不能证明Block内容正确，也不能验证定位效果。团队还应把期望的定位库名称、应用包名和发布环境写进CI变量，与清单逐项比较，避免测试配置进入正式包。
上线前做三次对齐
第一次是后台对齐：确认目标定位库中存在本次Block，状态可用，旧版本仍有明确去向。第二次是客户端对齐：在“关于”或诊断页显示releaseId、内容包版本和脱敏后的服务标识，现场人员不用接电脑就能辨认版本。第三次是证据对齐：用同一候选包完成固定点位、不同进入方向、冷启动和失去定位后的恢复测试，失败样本同样保留。
正式切换前再做一次反向演练：如果新版本异常，谁执行回滚、客户端是否需要重新发包、旧Block是否仍可用、现场人员如何确认恢复完成。没有演练过的rollbackTarget只是一个字符串，不是回滚能力。
常见问题
只记录Block版本够不够？ 不够。空间数据正确，但客户端仍可能指向错误定位库，或者加载了不匹配的内容包，所以至少要同时记录服务、应用和内容版本。
发布清单能不能包含密钥？ 不建议。清单通常会进入代码仓库、CI日志和项目群，应该只保留可识别但不敏感的对象名称或编号，凭证交给专门的密钥系统管理。
更新地图后是否必须全场复测？ 取决于变化范围。局部补采可以先覆盖受影响区域、邻接路线和恢复点；坐标基准、定位库或客户端融合逻辑变化时，应扩大回归范围。无论范围大小，都要在发布记录里写清选择依据。
真正可维护的大空间AR系统，不是“后台里有一张新地图”，而是任何现场问题都能追溯到一组确定版本，并且团队知道如何验证、切换和退回。
