- 移动开发
- 图像处理
【免费下载链接】Nuke
Image loading system
本文基于 Nuke 仓库 Documentation/Migrations/Nuke 11 Migration Guide.md 编写，帮助正在使用 Nuke 10.x 的应用平滑升级到 Nuke 11。你将掌握：自定义解码器与处理器 API 的 throwing 化改造、
hashableIdentifier默认实现的简化、invalidate()带来的全新错误语义，以及ImageRequestConvertible软弃用的应对策略。文中所有结论均可对照仓库源码验证，可作为迁移与排查的实操手册。
升级概览：最低系统要求
Nuke 11 提高了系统与工具链的最低要求，升级前请先确认工程环境满足以下条件：
| 项目 | 最低版本 |
|---|---|
| 平台 | iOS 13.0、tvOS 13.0、macOS 10.15、watchOS 6.0 |
| Xcode | 13.3 |
| Swift | 5.6 |
这些要求与 Nuke 11 引入的 async/await 等 Swift 并发特性直接相关（见下文「ImageRequestConvertible 软弃用」一节）。若你的工程仍部署在 iOS 12 及更早系统上，需要先提升 deployment target 再考虑迁移。
错误报告改进：解码与处理 API 全面 throwing 化
Nuke 11 最核心的破坏性变化，是把自定义解码器与处理器的主 API 从「可选值返回」改为「可抛异常」。这样实现方可以在失败时携带更多诊断信息，而不是默默返回nil让调用方无从排查。
ImageDecoding：decode(_:)变为 throwing
ImageDecoding协议的核心方法签名变化如下：
// Before (Nuke 10) public protocol ImageDecoding { func decode(_ data: Data) -> ImageContainer? } // After (Nuke 11) public protocol ImageDecoding { func decode(_ data: Data) throws -> ImageContainer }在迁移后的实现中，如果确实没有可报告的失败原因，可以抛出新引入的ImageDecodingContext.unknown占位错误。仓库中 Sources/Nuke/Decoding/ImageDecoding.swift 定义了对应的ImageDecodingError枚举，其中.unknown正是用于「无更多信息可报告」的场景：
public enum ImageDecodingError: Error, CustomStringConvertible, Sendable { case unknown @_spi(AsyncImageDecoding) case synchronousDecodingUnsupported public var description: String { switch self { case .unknown: "Unknown" case .synchronousDecodingUnsupported: "Synchronous decoding is not supported" } } }从源码结构看，解码失败后错误会沿管线向上传播：管道将decoderNotRegistered、decodingFailed等包装进ImagePipeline.Error（见 Sources/Nuke/Pipeline/ImagePipeline+Error.swift），ImagePipeline.Error.decodingFailed会携带 decoder、解码上下文与底层错误，让诊断信息不再丢失：
indirect case decodingFailed(decoder: any ImageDecoding, context: ImageDecodingContext, error: Swift.Error)需要说明的是，ImageDecodingContext本身也随 Nuke 11 进化，成为解码器选择与解码执行的核心上下文对象。当前仓库中的完整定义位于 Sources/Nuke/Decoding/ImageDecoderRegistry.swift，包含request、data、isCompleted、urlResponse、cacheType、previewPolicy、isAnimatedImageParsingEnabled等字段——ImageDecodingContext.unknown即指用.unknown错误表示「没有具体失败信息」。
ImageProcessing：容器级处理方法变为 throwing
ImageProcessing协议中，处理PlatformImage的基础方法保持不变，但处理ImageContainer（可携带元数据、动画帧等）的方法改为可抛异常：
// Before (Nuke 10) public protocol ImageProcessing { func process(_ image: PlatformImage) -> PlatformImage? func process(_ container: ImageContainer, context: ImageProcessingContext) -> ImageContainer? } // After (Nuke 11) public protocol ImageProcessing { func process(_ image: PlatformImage) -> PlatformImage? // This is now throwing. func process(_ container: ImageContainer, context: ImageProcessingContext) throws -> ImageContainer }仓库中的当前实现（Sources/Nuke/Processing/ImageProcessing.swift）为process(_:context:)提供了默认实现：调用基础方法process(image:)，若返回nil则抛出ImageProcessingError.unknown；成功时还会丢弃进入处理器的data与animation（避免处理器对静态结果错误播放原始动画）。如果你写的处理器自己逐帧处理动画，可以覆写该方法以保留这些信息。
public func process(_ container: ImageContainer, context: ImageProcessingContext) throws -> ImageContainer { try container.map { image in guard let output = process(image) else { throw ImageProcessingError.unknown } return output } }对应的错误类型ImageProcessingError同样只有一个.unknown占位 case（Sources/Nuke/Processing/ImageProcessing.swift），并在管道层被包装为ImagePipeline.Error.processingFailed：
indirect case processingFailed(processor: any ImageProcessing, context: ImageProcessingContext, error: Swift.Error)迁移实践要点
- 解码器：将
decode的返回类型由ImageContainer?改为ImageContainer，内部失败路径改为throw ImageDecodingError.unknown；渐进式解码（decodePartiallyDownloadedData）仍返回可选值，用于下载未完成时提供预览。 - 处理器：基础
process(_ image:)不动；若你实现了容器级方法，把失败路径从return nil改为throw ImageProcessingError.unknown。 - 错误上报：升级后
ImagePipeline.Error的decodingFailed/processingFailed会携带上下文与底层错误，配合 Sources/Nuke/Diagnostics/DiagnosticsRecorder.swift 的诊断记录器，可在解码/处理阶段精确记录失败的 decoder、processor 与耗时。
ImageProcessing 与 Hashable：删掉多余的 hashableIdentifier
Nuke 10 中，为了让处理器在缓存键与任务合并中高效比较，符合Hashable的处理器通常需要手动实现hashableIdentifier并返回self：
// Before (Nuke 10) extension ImageProcessors { public struct Resize: ImageProcessing, Hashable { private let size: CGSize var hashableIdentifier: AnyHashable { self } } }Nuke 11 为ImageProcessing where Self: Hashable提供了默认实现，因此这段样板代码可以整体删除：
// After (Nuke 11) extension ImageProcessors { public struct Resize: ImageProcessing, Hashable { private let size: CGSize } }仓库 Sources/Nuke/Processing/ImageProcessing.swift 中的默认实现即为：
extension ImageProcessing where Self: Hashable { public var hashableIdentifier: AnyHashable { self } }非Hashable的处理器则继续使用基于identifier字符串的默认实现（hashableIdentifier默认返回identifier）。当前仓库中的 ImageProcessors+Resize.swift 正是迁移后的形态：Resize只需声明ImageProcessing, Hashable, CustomStringConvertible，不再手写hashableIdentifier。
从源码注释（Sources/Nuke/Processing/ImageProcessing.swift）可以推断这一设计对性能的意义：内存缓存每次命中都要比较处理器，LazyImage每次视图更新也要比较，字符串的创建与比较代价较高；Hashable处理器直接返回self（装箱为AnyHashable），比较成本远低于字符串。请求创建时会将hashableIdentifier一次性装箱到ImageProcessorID中，之后所有比较都复用该装箱结果。
迁移检查清单
- 检查所有自定义处理器是否声明了
Hashable； - 若是，删除手写的
hashableIdentifier，改用默认实现； - 若处理器无法（或不希望）符合
Hashable，保留identifier字符串方案即可，行为不变。
失效机制（Invalidation）：新请求立即失败
Nuke 11 中，对管线调用invalidate()后，所有未完成的任务会被取消，任何新发起的请求都会立即以pipelineInvalidated错误失败，而不是继续排队等待。
对应实现见 Sources/Nuke/Pipeline/ImagePipeline.swift：
/// Invalidates the pipeline and cancels all outstanding tasks. Any new /// requests will immediately fail with ``ImagePipeline/Error/pipelineInvalidated`` error. nonisolated public func invalidate() { Task { @ImagePipelineActor in guard !self.isInvalidated else { return } self.isInvalidated = true ... } }错误定义位于 Sources/Nuke/Pipeline/ImagePipeline+Error.swift：
/// Image pipeline is invalidated and no requests can be made. case pipelineInvalidatedImagePipeline.Error.pipelineInvalidated的description为 "Image pipeline is invalidated and no requests can be made."。迁移提示：由于失效是全局性的，触发invalidate()（例如应用登出、切换账号、刷新缓存配置）后，需要同步重建或替换管线实例，才能恢复图片加载能力；同时建议在错误处理中对pipelineInvalidated做专门分支，避免把它当作普通网络错误上报。
ImageRequestConvertible 软弃用：拥抱 async/await API
ImageRequestConvertible最初在 Nuke 9.2 引入，目的是减少loadImage(:)系列 API 在代码补全中出现的数量。Nuke 11 全面采用 async/await 后，补全拥挤的问题不复存在，因此该协议被软弃用（soft-deprecated）：
- 基于闭包的旧 API（如
loadImage(:)）仍会继续兼容ImageRequestConvertible； - 新的 async/await API（如
image(for:)）只接受URL与ImageRequest，以提升可发现性与性能。
当前仓库中，image(for:)的签名（Sources/Nuke/Pipeline/ImagePipeline.swift）正是这一设计的结果：
nonisolated public func image(for url: URL) async throws(ImagePipeline.Error) -> PlatformImage { try await image(for: ImageRequest(url: url)) } nonisolated public func image(for request: ImageRequest) async throws(ImagePipeline.Error) -> PlatformImage { try await imageTask(with: request).image }而闭包式loadImage(with:)系列 API 保留在 Sources/Nuke/Pipeline/Deprecated.swift，供旧代码继续使用。
迁移建议
- 若你的代码通过自定义类型（或
URL、ImageRequest的扩展）来符合ImageRequestConvertible，建议现在就移除，改为直接传URL或构造ImageRequest； - 该协议在 Nuke 11 中不会正式弃用，正式移除要等到下一个大版本，因此不必紧急处理，但尽早清理可以降低未来升级成本；
- 使用
ImageRequestConvertible的旧 API 依旧可用，不需要立即改写调用点。
迁移顺序与自检清单
将以上变更汇总为推荐的迁移步骤：
- 评估环境：确认平台、Xcode、Swift 版本满足最低要求；
- 修改解码器：
decode(_:)改为throws -> ImageContainer，失败抛ImageDecodingError.unknown； - 修改处理器：容器级
process(_:context:)改为throws -> ImageContainer，失败抛ImageProcessingError.unknown；基础process(_ image:)保持不变； - 删除冗余
hashableIdentifier：Hashable处理器直接删除手写实现，交给默认实现； - 处理失效语义：检查
invalidate()调用点，为pipelineInvalidated错误增加专门处理； - 清理
ImageRequestConvertible：新代码一律使用URL/ImageRequest+image(for:)，旧调用点可暂缓。
完成上述步骤后，应用即可从 Nuke 10.x 平稳迁移到 Nuke 11。若迁移中遇到解码或处理阶段的异常，建议结合 Sources/Nuke/Diagnostics/DiagnosticsRecorder.swift 的记录能力定位具体失败环节。后续版本的迁移差异可参考仓库 Documentation/Migrations 目录下的其他迁移指南。
- 移动开发
- 图像处理
【免费下载链接】Nuke
Image loading system
相关推荐
Layui表格合计行架构深度解析：数据聚合与可视化统计的最佳实践
Layui表格合计行架构深度解析：数据聚合与可视化统计的最佳实践 在现代化Web应用开发中，数据表格不仅是信息的展示载体，更是数据分析与决策支持的核心界面。La
前端UI组件PrimeNG v21 迁移指南：无破坏升级策略、CSS 动画迁移与弃用 API 处理
PrimeNG v21 迁移指南：无破坏升级策略、CSS 动画迁移与弃用 API 处理 导读 本文是 PrimeNG（Angular UI 组件库）v21 的官
前端UI组件Streamlink 弃用与迁移指南：从 CLI 参数到插件 API 的完整升级路线图
Streamlink 弃用与迁移指南：从 CLI 参数到插件 API 的完整升级路线图 Streamlink 在持续演进的过程中，会定期将冗余、命名不当或设计过
音视频
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
