This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

通过为 EAS Observe 启用 Expo Image 集成，在你的生产应用中检测过大的图片。

expo-image 提供了一个可选择加入的 EAS 集成，用于观察那些解码后比设备屏幕显示尺寸大得多的图片。过大的图片会浪费带宽和内存，却不会提升视觉效果。该集成会为每张图片记录一个 expo-image.oversized 事件，这样你就可以在生产环境中找到它们，而不必手动审查每个屏幕。

先决条件

🌐 Prerequisites

启用集成

🌐 Enable the integration

在你的应用挂载之前，在模块作用域内用 expo-image 集成标志调用一次 Observe.configure()：

🌐 Call Observe.configure() once with the expo-image integration flag at module scope, before your app mounts:

import { Observe } from 'expo-observe';

Observe.configure({
  integrations: { 'expo-image': true },
});

不需要其他设置。一旦启用，该集成会自动监控每次图片加载。

🌐 No other setup is needed. Once enabled, the integration observes every image load automatically.

工作原理

🌐 How it works

每次加载图片时，集成都将图片解码后的像素尺寸与设备屏幕上的物理像素数量进行比较。当解码后的区域超过屏幕像素数超过配置的阈值时，集成会记录一个 expo-image.oversized 事件，严重性为 warn。

🌐 On every image load, the integration compares the image's decoded pixel size with the number of physical pixels on the device's screen. When the decoded area exceeds the screen's pixel count by more than the configured threshold, the integration logs an expo-image.oversized event with warn severity.

不同平台上，<Image> 组件渲染的图片在集成看到的解码尺寸会有所不同：

🌐 The decoded size that the integration sees differs between platforms for images rendered with the <Image> component:

• 在安卓上，<Image> 组件会在解码时将图片缩小到组件的尺寸，所以大图在小组件中显示时通常不会被报告。
• 在 iOS 上，集成会在 expo-image 缩小显示之前报告源文件的解码大小，所以即使启用了 allowDownscaling，在小组件中显示的大文件仍然会被报告。

使用 useImage 钩子或 Image.loadAsync 加载的图片默认会在两个平台上以源文件的完整尺寸解码。你可以通过 maxWidth 和 maxHeight 加载选项来限制解码后的尺寸。这样可以让各个平台报告的图片尺寸保持一致。

🌐 Images loaded with the useImage hook or Image.loadAsync decode at the source's full size on both platforms by default. You can limit the decoded size with the maxWidth and maxHeight load options. This makes the reported image dimensions consistent across platforms.

每个图片 URL 在每个应用会话中最多只会被上报一次。去重使用的是清理后的 URL，因此在默认配置下，只有查询参数不同的同一张图片的不同版本（比如旋转的签名 URL）也只会产生一次事件。

🌐 Each image URL is reported at most once per app session. Deduplication uses the sanitized URL, so with the default configuration, variants of one image that differ only in their query parameters (such as rotating signed URLs) produce a single event.

事件属性：

事件会在设备外发送，所以集成会在上报之前对图片 URL 进行清理：

🌐 Events are dispatched off-device, so the integration sanitizes the image URL before reporting it:

• 查询字符串和片段默认会被移除，因为查询参数通常包含敏感信息，比如签名令牌或 API 密钥。可以设置 includeUrlParams 选项来报告完整的 URL。
• 无论 includeUrlParams 是什么，基本认证凭据总是会被移除。
• 只有 http(s)、file 和 android.resource 的网址会被报告。其他协议，比如 data: 或 ph://，会携带图片内容或稳定的个人照片标识，所以它们永远不会离开设备。

urlSanitized 属性会告诉你清理是否更改了报告的 URL。URL 是以规范化（WHATWG）形式报告的，仅仅规范化本身不算作更改。

🌐 The urlSanitized attribute tells you whether sanitization changed the reported URL. URLs are reported in normalized (WHATWG) form, and normalization alone does not count as a change.

配置

🌐 Configuration

传递一个配置对象而不是 true 来调整图片报告的时间:

🌐 Pass a configuration object instead of true to tune when an image is reported:

import { Observe } from 'expo-observe';

Observe.configure({
  integrations: {
    'expo-image': {
      oversizeThreshold: 2,
    },
  },
});

• oversizeThreshold：当解码后的图片像素面积超过屏幕物理像素数的这个倍数时，会报告该图片。默认值是 1.5，这可以为全屏图片留出加上50%余量的空间。
• includeUrlParams：是否在报告的事件中包含图片 URL 的查询字符串和片段。默认值是 false：在 URL 离开设备之前会截断这些部分，因为查询参数通常包含敏感信息，比如签名令牌或 API 密钥。只有当你的图片 URL 可以安全地完整发送到设备外时才启用这个选项。无论此设置如何，基本认证信息总是会被移除。

修复过大的图片

🌐 Fix oversized images

• 尽量用接近显示大小的图片，比如可以向你的图片 CDN 请求调整过大小的版本。
• 在使用useImage钩子加载图片时，设置maxWidth和maxHeight加载选项，以在解码时按原始宽高比缩小图片。

查看事件

🌐 View events

在仪表板中：打开你的项目，导航到 观察 > 事件，然后选择 expo-image.oversized 事件以查看包含属性和会话的单独报告。

🌐 In the dashboard: open your project, navigate to Observe > Events, and select the expo-image.oversized event to see individual reports with their attributes and sessions.

从命令行接口（CLI）:

🌐 From the CLI:

有关所有事件共有的命名、严重性和属性详情，请参见 用户自定义事件。

🌐 For naming, severity, and attribute details shared by all events, see User-defined events.