expo-asset 解析Expo 通用资源模块的资源下载、本地缓存与统一资产管理机制【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expoexpo-asset是 Expo SDK 中的通用资源模块负责将应用中的图片、字体、媒体等静态资源下载到设备本地并统一封装成带元数据的Asset对象传递给其他原生与 JS API 使用。它同时兼容 Android、iOS 与 Web 三端覆盖开发期、生产构建与基于 expo-updates 的本地资源解析等场景。读完本文你将掌握 expo-asset 的安装方式、Asset/useAssets的核心 API、MD5 哈希缓存机制以及它在 Metro 打包、Expo 原生插件、React Server Components 中的底层协作原理。模块定位Assets 的下载器与资源元数据统一入口在 Expo / React Native 应用中静态资源有两种存在形式一种是随 JS Bundle 一起由 Metro 打包并登记到 asset registry 的“内置资源”另一种是运行时通过 URL 指向的远端资源。二者形态各异但下游 API例如Image、Font.loadAsync、Audio往往只关心“资源在设备上的本地文件路径”。expo-asset 正是为了解决这一统一问题而存在。其 package.json 中的描述也是 README 的开篇定义非常精炼An Expo universal module to download assets and pass them into other APIs即下载资源并将其交付给其他 API 使用。从代码结构看这个职责被拆成了两半JS 层 Asset.ts 维护每个资源的元数据name、type、hash、uri、localUri、宽高并负责生命周期管理是否已下载、是否正在下载原生层Android 的AssetModule.kt与 iOS 的AssetModule.swift通过 expo-modules-core 暴露ExpoAsset原生模块真正执行“从 URL 下载到本地缓存目录”这一底层操作。模块在仓库中的当前版本为57.0.8见 package.json通过 expo-module.config.json 声明为自动链接的原生模块。源码结构一眼看懂模块分层从 packages/expo-asset 目录结构可以看出典型的 Expo 模块“三明治”式组织目录 / 文件职责src/Asset.tsAsset类的核心实现元数据、工厂方法与下载生命周期src/Asset.fx.tsside-effect 模块覆盖 React Native 的Image资源解析逻辑src/AssetHooks.tsReact HookuseAssetssrc/AssetSources.ts依据 manifest 与平台选择资源远端地址selectAssetSourcesrc/AssetUris.tsURL 工具文件名、扩展名、manifest base URL 提取src/ImageAssets.tsWeb 端图片尺寸探测src/LocalAssets.ts从 expo-updates 暴露的localAssets映射中按哈希找本地文件src/ExpoAsset.ts通过requireNativeModule调用原生downloadAsyncsrc/resolveAssetSource.ts包装 RN 的Image.resolveAssetSourceandroid/.../AssetModule.ktAndroid 原生下载与缓存实现ios/AssetModule.swiftiOS 原生下载与缓存实现plugin/src/withAssets.ts等Expo config plugin把资源嵌入原生工程tools/hashAssetFiles.jsMetro 自定义资源哈希工具mocks/ExpoAsset.ts测试用 mock入口 src/index.ts 非常简单先引入./Asset.fx触发资源解析覆盖逻辑再对外导出Asset与useAssets。安装方式托管工作流与 bare React Native 工作流README 针对两种项目形态给出了不同的安装路径。managed托管Expo 项目在 managed 工作流中跟随官方 API 文档安装即可运行npx expo install expo-asset时expo CLI 会依据项目中的 Expo SDK 版本自动选定兼容的 expo-asset 版本无需手工处理依赖版本与原生工程。README 同时提醒若跟随文档链接后没有任何可用文档说明该库尚未进入当前 SDK 的可用范围通常会随下一个 SDK 版本发布。bare React Native 项目bare 项目需要先完成前置条件安装并配置好expo核心包也就是 Expo 模块的 autolinking 基础设施然后执行npx expo install expo-asset该命令会完成依赖安装与原生模块的自动链接。安装后如需支持本地资源嵌入等能力还涉及原生工程的重新构建。之所以必须“先装 expo”从代码依赖也能印证expo-asset 的 package.json 在dependencies中依赖expo-constants与expo/image-utils同时把expo、react、react-native声明为peerDependencies其源码也大量直接引用expo-modules-core提供的requireNativeModule等基础设施见 ExpoAsset.ts。Asset 类资源的元数据模型Asset.ts 中的Asset是 expo-asset 对外暴露的核心数据模型。它记录了资源的完整信息并提供加载能力name资源文件名不含扩展名也去掉文件名中后的倍率标记type资源扩展名hash资源数据的 MD5 哈希用于判重与缓存命中uri资源在远端服务器的地址。开发期指向运行 expo CLI 的电脑并由其直接伺服生产发布版指向资源服务器在正确配置的更新场景下该字段应被忽略因为 expo-updates 会保证资源在运行业务逻辑前已就位于设备localUri调用downloadAsync()成功后指向设备本地文件的file://URIwidth/height图片数据宽度与高度除以缩放倍率后的逻辑尺寸倍率即文件名中之后的数字缺省为 1downloaded是否已完成一次下载。构造时如果资源带hash构造函数会尝试通过getLocalAssetUri(hash, type)立刻找到本地文件见 Asset.ts。对 Android 的嵌入式资源file:///android_res/前缀有专门处理它们不视为“已下载”因为该 URI 不能直接访问此时uri直接指向该内嵌地址。常用 API 与典型使用场景批量加载Asset.loadAsyncAsset.loadAsync(moduleId)接受一个或多个require(path/to/file)的模块 ID、外部网络 URL或带{ uri, width, height }的对象内部等价于对每一项调用Asset.fromModule(...).downloadAsync()后Promise.all见 Asset.ts。import { Asset } from expo-asset; // 下载一个本地图片资源并取得其在设备上的本地路径 const [{ localUri }] await Asset.loadAsync(require(./assets/snack-icon.png)); // 也支持网络 URL const [remoteAsset] await Asset.loadAsync(https://example.com/icon.png);从模块或 URL 获取 Asset 实例Asset.fromModule(virtualAssetModule)是核心工厂方法见 Asset.ts输入有三种形态内部走三条不同分支字符串视为网络 URL调用Asset.fromURI(url){ uri, width, height }对象直接构造 Asset多用于流式加载场景数字模块 ID即require(...)的返回值通过 RN 的getAssetByID从 asset registry 读取元数据name/type/hash/宽高再依据环境选择resolveAssetSource或Asset.fromMetadata完成构造。Asset.fromURI与Asset.fromMetadata都带有缓存Asset类内部维护了byHash与byUri两个静态字典同一哈希或同一 URL 只会构造一个共享实例见 Asset.ts避免重复下载与重复占用内存。React HookuseAssets对组件内场景expo-asset 提供了声明式 HookuseAssets见 AssetHooks.tsimport { useAssets } from expo-asset; import { Image } from react-native; export default function App() { const [assets, error] useAssets([ require(path/to/asset.jpg), require(path/to/other.png), ]); if (error) { return Text资源加载失败: {error.message}/Text; } return assets ? Image source{assets[0]} / : null; }注意两点返回值中资源列表在加载完成前是undefined错误单独放在第二位并且按官方注释的说明当传入的资产列表动态变化时Hook 不会重新触发加载其useEffect依赖数组为空见 AssetHooks.ts。downloadAsync 与缓存命中机制JS 侧的状态机downloadAsync()是下载的唯一入口Asset.ts 用两个标志位实现了一个小型状态机若downloaded为 true直接返回自身本地已有最新文件若downloading为 true则把当前调用者挂入_downloadCallbacks队列等待否则置downloading true开始下载成功后统一 resolve 队列中的所有等待者最终把文件路径写入localUri。Web 平台上还有一个额外的分支图片类型资源会先用ImageAssets.getImageInfoAsync解析出真实宽高并回填元数据见 Asset.ts这是 JSImage对象在 Web 上常用的异步探测手段具体实现见 ImageAssets.ts。原生侧缓存文件命名与哈希校验JS 层最终通过 ExpoAsset.ts 里的downloadAsync(url, md5Hash, type)调用原生模块ExpoAsset。看 Android 实现AssetModule.kt可以还原完整逻辑若 URI 本身就是filescheme且非 Android 内嵌资源直接原样返回不做二次下载计算缓存文件标识cacheFileId优先使用传入的md5Hash否则对 URI 路径字符串做一次 MD5目标文件固定写入应用 cache 目录命名为ExponentAsset-{cacheFileId}.{type}若该文件尚不存在则直接下载若已存在则比较其内容 MD5 与md5Hash不一致才重新下载——这实现了“本地已是最新则跳过网络请求”的缓存命中逻辑。JS 侧 Asset.ts 的文档注释明确给出了两条使用注意事项downloadAsync把文件写入caches 目录因此不保证跨 App 会话持久存在——系统可能自行清理或由用户手动清空缓存如需手动清理可借助 expo-file-system 删除缓存目录如Paths.cache.delete()或旧版 APIdeleteAsync(cacheDirectory)。Android 侧还做了目录写权限校验与空文件告警下载得到的字节数为 0 时会打印Asset downloaded to ... is empty...的警告日志见 AssetModule.kt。资源地址选择selectAssetSource 的分层决策一个资源文件在何种环境下应从哪里下载是由 AssetSources.ts 的selectAssetSource(meta)决定的它是 expo-asset 在“下载”之外的另一核心逻辑。其决策链大致如下按像素密度选文件依据PixelRatio.get()在meta.scales中挑选最匹配的倍率并取出该倍率对应的fileHashes[index]与fileUris[index]fileUris 优先若 asset 元数据里提供了显式文件 URI可由资源处理管线注入直接解析为绝对地址返回绝对 http(s) 位置httpServerLocation若本身是完整 URL则拼出{文件名}{scale}x.{ext}并带上platform、hash查询参数开发服务器使用 manifest2 中的debuggerHost或 bundle origin 推导出 dev server 地址再拼接Expo Go 的 classic assets作为临时 fallback 使用https://classic-assets.eascdn.net/~assets/{hash}最终兜底当资源由 expo-updates 管理、已经本地化时返回空串 URI 占位此时getLocalAssetUri(hash)必然能返回本地路径。这套逻辑与 React Native 的AssetSourceResolver同源但额外支持了文件哈希与显式 URI 两条通道覆盖了 expo-updates 分发、资源处理管线如图片压缩/格式转换等更现代的资产工作流。与 expo-updates 的协作本地资源直读在 OTA 更新expo-updates环境中JS Bundle 更新时会顺带下载引用到的资源并把“hash → 本地 URI”的映射表交给应用。expo-asset 通过可选依赖注入而非强依赖来消费这份数据它在 PlatformUtils.ts 用requireOptionalNativeModule(ExpoUpdates)获取原生模块若未安装则优雅降级。LocalAssets.ts 的getLocalAssetUri(hash, type)在查找时支持两种 key 格式新格式直接用 hash 作为 key旧的更新包由于带扩展名存储使用{hash}.{type}的 legacy key 兼容查找。构造 Asset 时若按 hash 找到本地文件downloaded会被直接置为 true——这正是“运行更新包时代码执行前资源已就位”的机制基础。相应地IS_ENV_WITH_LOCAL_ASSETSExpo Go 环境、或已启用且非 embedded bundle 的 expo-updates 环境决定是否启用本地资源解析模式见 PlatformUtils.ts。覆盖 RN 的 Image 资源解析Asset.fx.tsexpo-asset 还通过副作用模块 Asset.fx.ts 在本地资源模式下替换 React NativeImage组件默认的资源解析器实现 JS 侧资源解析与 expo-asset 的无缝统一。其原理是通过setCustomSourceTransformer注入一个 transformer见 Asset.fx.ts当打包器启用了 expo-asset 的哈希插件元数据中存在fileHashes字段时走Asset.fromMetadata分支已下载则让Image直接使用asset.localUri否则先用远端asset.uri并交给 expo-asset 的下载流程托管Android 内嵌 drawable 资源file:///android_res/则退化为resourceIdentifierWithoutScale()让 RN 直接按资源 ID 引用任何异常都会回落到resolver.defaultAsset()保证失败不至于阻塞渲染。整个注册过程受到IS_ENV_WITH_LOCAL_ASSETS的开关保护——若应用直接运行 embedded bundle不使用更新的本地资产则不会做多余的重写。Config Plugin 与构建期资源哈希expo-asset 通过app.plugin.js见 app.plugin.js暴露 Expo config plugin其源码位于 plugin/src核心是withAssets它把通过require引用的本地资源直接复制进 iOS / Android 原生工程withAssetsIos.ts / withAssetsAndroid.ts使资源在无 Metro 服务或原生侧直接消费的场景下依然可用。构建期还需要一个关键工具Metro 打包时的hashAssetFiles实现见 tools/hashAssetFiles.js并通过 package.json 的./tools/hashAssetFiles子路径导出。它把每个资源的哈希写入打包产物中的fileHashes元数据正是Asset.fx.ts判断“是否启用哈希解析”以及downloadAsync拿到md5Hash参数进行缓存命中的前提。仓库中也提供了对原生下载与哈希行为的单元测试如 FileUtilsTest.kt以及 JS 层测试套件src/tests覆盖Asset构造、AssetSources、LocalAssets、图片资源解析与 Web 端行为。React Server Components 支持值得注意的是expo-asset 的 package.json 为react-server条件导出了专门的入口./src/index.server.ts。仓库中存在独立的 Asset.server.ts 与 index.server.ts说明该模块已适配 React Server ComponentsRSC——服务端环境不使用浏览器Image对象也不会执行原生下载相关内容按 RSC 边界做相应实现。对于在服务端渲染或流式场景中引用静态资源元数据的项目这是版本 SDK 内值得关注的现代能力。小结以 README 中的定义回看整个模块expo-asset 本质上是一条“元数据 下载 缓存 地址解析”的完整资源管线。它在 JS 层以Asset类与useAssets提供统一模型在原生层以带 MD5 校验的ExponentAsset-{hash}.{type}缓存文件实现去重与命中判断在解析层通过selectAssetSource覆盖开发服务器、生产 CDN、Expo Go 与 expo-updates 等多种来源并以 config plugin、Metro 哈希工具与 RSC 入口补齐了构建期与服务端的能力闭环。当你需要手动预加载字体、图片并取得其本地路径时Asset.loadAsync与useAssets就是 expo-asset 交给你的标准答案。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考