顺序访问、随机访问与实体化
访问模式决定 Pipeline 可以按什么顺序向加载器请求像素。它和“文件是不是流”不是同一件事：一个按顺序模式打开的 JPEG，仍然可能被后续操作要求回头读取。
三种访问方式
Section titled “三种访问方式”| 方式 | 加载器承诺什么 | 适合什么 |
|---|---|---|
| 随机访问（Random access） | 可以按任意区域、多次读取 | 方向不确定、要裁智能区域、或同一图像要服务多个输出 |
| 顺序访问（Sequential access） | 通常只能从上到下读一次 | 缩小、水平翻转、多数按行卷积、单次转码 |
| 实体化（Materialisation） | 先将解码结果完整缓冲到内存或临时文件，再提供随机读取 | 顺序流后面必须做随机操作时的显式代价 |
顺序访问需要调用方显式开启。govips 用导入参数里的 AccessSequential，sharp 用 sequentialRead: true，pyvips 用 access="sequential"，CLI 用 [access=sequential]。未设置时，四个入口的默认缓冲策略并不完全相同。
错误为什么出现在导出时
Section titled “错误为什么出现在导出时”导出器从结果图像往回请求像素。顺序加载器只能继续向前读。一旦某个操作需要底部的行、需要重读已经放过的行，或者需要把同一条顺序 Pipeline 分给两个消费者，加载器就会拒绝。
因此排查顺序是：
- 看输入是按顺序模式打开，还是已经实体化（完整解码并缓冲到内存或临时文件）。
- 看失败前的最后一个操作是否需要随机读取。
- 看错误是在
Export、Save还是 CLI 写出文件时出现。
哪些操作会打破顺序读取
Section titled “哪些操作会打破顺序读取”顺序路径通常可以完成：按比例缩小、提取靠上的区域、水平翻转、颜色空间转换和 flatten。
以下操作通常需要随机访问或整图实体化：90° 及 180° 旋转、垂直翻转、基于熵或注意力的智能裁剪，以及对同一顺序图像的第二次读取。需要它们时，应在加载前改用随机访问，或先实体化再变换。
实体化换来的是随机读取能力，代价是更多内存或临时磁盘占用。它不是缓存未命中，也不能靠重试消除。
- 在Reader/Writer 流式 I/O中查看 Reader/Writer 与顺序访问开关的差别。
- 在排查 out of order read中查看已复现的失败路径与修复方式。