【Bug已解决】[Build] mp11 dependency fails to download in offline build due to missing URL_HASH 解决方案

【Bug已解决】[Build] mp11 dependency fails to download in offline build due to missing URL_HASH 解决方案一、现象长什么样在离线构建提前把所有第三方依赖下载到本地缓存目录、构建时断网或内网无外网ONNX Runtime 时其中一个依赖mp11Boost.MP11header-only 元编程库的下载步骤失败导致整个构建中断。报错指向下载/校验环节。现象# 现象 A离线构建时下载步骤仍尝试联网 # CMake Error at mp11.cmake: URL_HASH is not set, refusing to use # the locally cached download (CMake requires URL_HASH to trust cache) # 现象 B即使本地已有 mp11 压缩包仍报校验失败/重新下载 # 因为没写 URL_HASHCMake 的 ExternalProject/FetchContent 在 # try local cache 时不信任该文件强制重新从 URL 拉取 - 离线即失败 # 现象 C只在离线/内网环境触发 # 有外网时 CMake 直接下载成功URL_HASH 缺失被掩盖 # 离线时才暴露“缺 URL_HASH 导致无法信任本地缓存”最坑的是现象 C有网时一切正常CI/个人开发者都以为没问题一到客户内网/离线构建机就卡死且报错信息不直接指向“缺 URL_HASH”排查费时。二、背景CMake 的FetchContent/ExternalProject_Add在下载依赖时如果指定了URL_HASH如URL_HASH SHA256xxxx它会① 下载后校验完整性②更关键的是在离线/缓存场景下CMake 会用URL_HASH在本地缓存FETCHCONTENT_SOURCE_DIR或 download cache里按 hash 找/信任该文件。如果URL_HASH没写CMake 出于安全考虑拒绝使用未经验证的本地缓存强制重新联网下载于是离线构建直接失败。ONNX Runtime 的mp11.cmake在声明这个依赖时漏写了URL_HASH可能最初是GIT_REPOSITORY后来改成URL下载但没补 hash于是离线构建踩坑。这是构建系统/依赖管理审查里典型的坑依赖下载声明缺URL_HASH在线时被掩盖、离线时因无法信任本地缓存而失败。三、根因mp11下载声明缺URL_HASH从URL下载却没写URL_HASHCMake 不信任本地缓存 → 离线失败现象 A/B。离线缓存信任依赖 hashCMake 的 download-cache 机制靠URL_HASH来命中/信任本地文件没有 hash 就强制联网。缺少离线构建冒烟测试CI 只用在线构建离线/内网场景从未覆盖缺 hash 长期存在。本质是依赖下载声明缺URL_HASH导致 CMake 离线时无法信任本地缓存而强制联网失败且缺离线冒烟测试。四、最小可运行复现下面用 Python 模拟“缺 URL_HASH 时CMake 拒绝信任本地缓存、强制联网离线即失败”def fetch_dep_buggy(url, local_cache_has, url_hashNone, onlineFalse): buggy: 没 URL_HASH不信任本地缓存。 if url_hash is None: # CMake 无法信任缓存必须联网 if not online: return False, no URL_HASH - cannot trust cache - need network (offline fails) return True, downloaded online # 有 hash离线也能用本地缓存 if local_cache_has: return True, used trusted local cache if online: return True, downloaded cached return False, no cache and offline def fetch_dep_fixed(url, local_cache_has, url_hashsha256:abc..., onlineFalse): if local_cache_has and url_hash: return True, used trusted local cache if online: return True, downloaded cached return False, no cache and offline print(fetch_dep_buggy(mp11.tar.gz, local_cache_hasTrue, onlineFalse)) # (False, no URL_HASH - cannot trust cache ...) print(fetch_dep_fixed(mp11.tar.gz, local_cache_hasTrue, onlineFalse)) # (True, used trusted local cache)buggy离线失败fixed离线用缓存成功。五、解决方案第一层最小直接修复最小修复在mp11.cmake的依赖声明里补上URL_HASH并配URL与DOWNLOAD_EXTRACT_TIMESTAMP# 修正为 mp11 下载补上 URL_HASH FetchContent_Declare( mp11 URL https://github.com/boostorg/mp11/archive/refs/tags/boost-1.84.0.tar.gz URL_HASH SHA256eea224ea3c4c80bdf9bobo... # 真实 sha256 DOWNLOAD_EXTRACT_TIMESTAMP TRUE ) FetchContent_MakeAvailable(mp11)这样离线构建时 CMake 用URL_HASH在本地缓存信任并复用mp11压缩包不再强制联网。这一层改动最小补一行URL_HASH离线恢复。但依赖“每个依赖都写对 hash”下看第二层。六、解决方案第二层结构性改进把“所有第三方依赖下载必须带URL_HASH、且离线可信任缓存”固化成单一事实来源。下面这个 dataclass 集中管理依赖清单的校验契约from dataclasses import dataclass, field from typing import Dict dataclass class Mp11OfflinePolicy: 单一事实来源第三方依赖下载声明的完整性契约。 # 依赖名 - 期望的 URL_HASHSHA256 _hashes: Dict[str, str] field(default_factorylambda: { mp11: SHA256:eea224ea3c4c80bdf9bobo00000000000000000000000000000000000000abcd, # 其他依赖... }) def verify_declaration(self, dep: str, declared_hash: str None) - None: expected self._hashes.get(dep) if expected is None: raise ValueError(funknown dependency {dep}; add its hash) if declared_hash ! expected: raise AssertionError( fdependency {dep} must declare URL_HASH{expected}, fgot {declared_hash}) def can_use_offline_cache(self, dep: str, declared_hash: str) - bool: # 有正确 hash 才能信任本地缓存离线可用 try: self.verify_declaration(dep, declared_hash) return True except AssertionError: return False这一层的关键收益hash 集中管理所有依赖的URL_HASH在_hashes缺哪个一目了然离线可用判定can_use_offline_cache用 hash 正确与否决定是否信任本地缓存单一事实来源所有依赖完整性约定收口在Mp11OfflinePolicy。七、解决方案第三层断言 / CI 守护把第二层钉成 pytest挂进 CI作为依赖声明门禁含离线模拟import pytest from your_package.mp11_offline import Mp11OfflinePolicy def test_mp11_requires_hash(): # 断言 1mp11 必须有正确 URL_HASH p Mp11OfflinePolicy() with pytest.raises(AssertionError): p.verify_declaration(mp11, declared_hashNone) p.verify_declaration(mp11, p._hashes[mp11]) # 正确 hash 通过 def test_offline_cache_trusted_with_hash(): # 断言 2有正确 hash 才能离线用缓存 p Mp11OfflinePolicy() assert p.can_use_offline_cache(mp11, p._hashes[mp11]) is True def test_offline_cache_rejected_without_hash(): # 断言 3无 hash 离线不可用复现原 bug p Mp11OfflinePolicy() assert p.can_use_offline_cache(mp11, None) is False def test_unknown_dep_rejected(): # 断言 4未知依赖报错强制登记 hash p Mp11OfflinePolicy() with pytest.raises(ValueError): p.verify_declaration(unknown, SHA256:x)四条断言从“mp11 需 hash”“离线可信”“无 hash 拒”“未知拒”四面把缺 hash 回归钉死在 CI。八、排查清单离线/内网构建某个第三方依赖下载失败时报错是否指向“URL_HASH 未设置 / 无法信任缓存”是就确认该依赖的FetchContent_Declare漏了URL_HASH现象 A。有网时正常、离线才失败典型“缺 hash 被掩盖”查所有URL下载是否都带URL_HASH。本地缓存已有压缩包但仍重新下载就是缺 hash 导致 CMake 不信任缓存。用第二层Mp11OfflinePolicy依赖 hash 集中 离线可信判定 CI 门禁。加第三层 pytest断言“mp11 需 hash、离线可信、无 hash 拒、未知拒”。任何URL下载的依赖声明里都必须带URL_HASH否则离线构建必然失败。九、小结ORT 离线构建时mp11下载失败本质是依赖声明漏写URL_HASHCMake 出于安全不信任本地缓存、强制重新联网离线环境即失败在线时被掩盖、缺离线冒烟测试。修复分三层——第一层在mp11.cmake补URL_HASH第二层用Mp11OfflinePolicy这个 dataclass 把所有依赖的 hash 收口成单一事实来源并用can_use_offline_cache判定离线可用性第三层用四条 pytest 把“mp11 需 hash、离线可信、无 hash 拒、未知拒”钉死在 CI。核心心法任何URL下载的第三方依赖都必须声明URL_HASH否则 CMake 离线时无法信任本地缓存而被迫联网——在线正常、离线必败。