iOS 照片选择、相机拍摄与媒体处理：用 PhotoKit…

适用于 iOS 16+ Swift 应用中使用 PhotosPicker、PHPickerViewController、AVCaptureSession、图片加载与照片/相机权限时。

适用场景

解决思路

1. 用 PhotosPicker（SwiftUI）或 PHPickerViewController（UIKit）替代 UIImagePickerController；PhotosPicker 在进程外运行，浏览无需相册权限，支持单选/多选和媒体类型过滤。
2. 单选：声明 selectedItem 为 PhotosPickerItem? 和 selectedImage 为 Image?；用 PhotosPicker 绑定 selection: $selectedItem、matching: .images；在 onChange(of: selectedItem) 中启动 Task，用 try? await newItem?.loadTransferable(type: Data.self) 读取 Data，并用 UIImage(data:) 转成 Image(uiImage:)。
3. 多选：声明 selectedItems 为 [PhotosPickerItem] 和 selectedImages 为 [Image]；用 PhotosPicker 绑定 selection: $selectedItems、maxSelectionCount: 5、matching: .images；在 onChange(of: selectedItems) 中启动 Task，清空 selectedImages，然后逐个 item 用 loadTransferable(type: Data.self) 读取 Data，转成 UIImage 后追加 Image(uiImage:)。
4. 媒体类型过滤：用 PHPickerFilter 组合限制可选媒体，例如 .images、.videos、.livePhotos、.screenshots、.any(of: [.images, .videos])、.all(of: [.images, .not(.screenshots)])。
5. 用 Transferable 加载选中项：定义 PickedImage: Transferable，包含 data: Data 和 image: Image；实现 static transferRepresentation，用 DataRepresentation(importedContentType: .image) 闭包，guard UIImage(data:) 成功否则抛 TransferError.importFailed，返回 PickedImage；定义 enum TransferError: Error { case importFailed }；用 try? await item.loadTransferable(type: PickedImage.self) 获取结果。
6. 始终在 Task 中异步加载 PhotosPickerItem，避免阻塞主线程；处理 loadTransferable 返回 nil 和抛错，因为用户可能选择无法解码的格式。
7. 照片库访问级别：Add-only 用于只写入不读取，Info.plist 用 NSPhotoLibraryAddUsageDescription；Read-write 用于完整或受限读取加写入，Info.plist 用 NSPhotoLibraryUsageDescription；PhotosPicker 浏览无需权限，只在需要读取完整库或保存照片时请求显式权限。
8. 检查并请求照片库权限：调用 PHPhotoLibrary.authorizationStatus(for: .readWrite)；switch status，notDetermined 时 await PHPhotoLibrary.requestAuthorization(for: .readWrite)；authorized 或 limited 直接返回；denied 或 restricted 直接返回；unknown default 返回 status。
9. 相机权限：在 Info.plist 加 NSCameraUsageDescription；检查 AVCaptureDevice.authorizationStatus(for: .video)；notDetermined 时 await AVCaptureDevice.requestAccess(for: .video)；authorized 返回 true；denied 或 restricted 返回 false；unknown default 返回 false。
10. 处理被拒绝的权限：显示 ContentUnavailableView，带 Access Denied 标签和 lock.shield 图标，description 显示说明，actions 提供 Open Settings 按钮；按钮用 URL(string: UIApplication.openSettingsURLString) 和 openURL 跳转设置；不要反复弹窗或静默隐藏功能。
11. 必须的 Info.plist 键：NSPhotoLibraryUsageDescription 用于读取照片；NSPhotoLibraryAddUsageDescription 用于保存照片/视频；NSCameraUsageDescription 用于访问相机；NSMicrophoneUsageDescription 用于录制音频（带声音的视频）；缺少必需键时权限弹窗出现会导致运行时崩溃。
12. 相机采集基础：每个采集会话由专用 controller 持有；在同一非主线程 executor 上串行化配置、startRunning() 和 stopRunning()；不要把主 actor 配置与 detached start/stop 混用；beginConfiguration()/commitConfiguration() 和会话状态变化不能竞争；representable view 只负责显示预览。
13. 相机最小生命周期：1 在会话配置事务外请求访问权限；2 在 capture executor 上调用 beginConfiguration() 并立即安装 defer { commitConfiguration() }，使每个提前返回都平衡事务；3 只在 canAddInput/canAddOutput 检查通过后添加输入输出；4 在同一 executor 上 start 或 stop，同步调用返回后只在主 actor 发布 UI 状态；5 失败时 stop、恢复新的 session 夹具、修复配置，并重新运行授权、前后台、中断和采集检查。
14. SwiftUI 相机预览：把 AVCaptureVideoPreviewLayer 包装进 UIViewRepresentable；makeUIView 设置 previewLayer.session = session 和 videoGravity = .resizeAspectFill；updateUIView 中若 previewLayer.session 不是当前 session 则更新；PreviewView 重写 layerClass 为 AVCaptureVideoPreviewLayer.self；previewLayer 返回 layer as! AVCaptureVideoPreviewLayer。
15. 在视图中使用相机：声明 @State private var cameraManager = CameraManager()；用 ZStack 放 CameraPreview(session: cameraManager.session).ignoresSafeArea() 和拍摄 Button；用 .task 执行 await cameraManager.configure() 后 cameraManager.start()；用 .onDisappear 执行 cameraManager.stop()；始终在 onDisappear 停止，因为运行中的采集会话独占相机并耗电。
16. 远程图片加载：用 AsyncImage(url:) 按 phase 分支：empty 显示 ProgressView，success 显示 image.resizable().scaledToFill()，failure 显示 systemName 为 photo 的占位图并设置 foregroundStyle(.secondary)，unknown default 显示 EmptyView；外层设置 frame 和 clipShape(.rect(cornerRadius: 12))。
17. AsyncImage 不会跨视图重绘缓存图片；生产环境大量图片要用专用图片加载库或基于 URLCache 的缓存。
18. 大图降采样：实现 downsample(data:to:scale:)，scale 默认 UITraitCollection.current.displayScale；maxDimensionInPixels = max(pointSize.width, pointSize.height) * scale；options 设置 kCGImageSourceCreateThumbnailFromImageAlways 为 true、kCGImageSourceShouldCacheImmediately 为 true、kCGImageSourceCreateThumbnailWithTransform 为 true、kCGImageSourceThumbnailMaxPixelSize 为 maxDimensionInPixels；guard 用 CGImageSourceCreateWithData(data as CFData, nil) 和 CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary)，否则返回 nil；返回 UIImage(cgImage: cgImage)。
19. 在列表、网格或缩略图中显示用户选择的照片时使用上述降采样；把 PhotosPickerItem 的原始 Data 直接传给降采样器，再创建 UIImage；一张 48MP 照片未压缩可超过 200 MB。
20. 图片渲染模式：.original 用于照片和艺术作品，按原始颜色显示；.template 用于图标，使其采用当前 tint 颜色，例如设置 renderingMode(.template) 和 foregroundStyle(.red)。
21. 常见错误：不要用 UIImagePickerController 做照片选择；用 PhotosPicker（SwiftUI）或 PHPickerViewController（UIKit）。
22. 常见错误：只在需要用户挑选照片时不要请求完整照片库权限；用 PhotosPicker 无需权限，或请求 .readWrite 让系统处理受限访问。
23. 常见错误：不要为缩略图加载全分辨率图片；用 CGImageSource 和 kCGImageSourceThumbnailMaxPixelSize 降采样。
24. 常见错误：不要在加载 PhotosPickerItem 数据时阻塞主线程；在 Task 中用 async loadTransferable(type:)。
25. 常见错误：不要忘记在视图消失时停止 AVCaptureSession；在 onDisappear 或 dismantleUIView 中调用 session.stopRunning()。
26. 常见错误：不要假设相机权限已授予；检查 AVCaptureDevice.authorizationStatus(for: .video) 并处理 .denied/.restricted。
27. 常见错误：不要在主线程序调用 session.startRunning()；在拥有配置和停止操作的同一专用串行 executor 上运行，因为它是同步阻塞调用，硬件初始化可能耗时数百毫秒。
28. 常见错误：不要在 UIViewRepresentable 内创建 AVCaptureSession；在单独的 @Observable model 中持有。
29. 审查清单：确认使用 PhotosPicker 而非已弃用的 UIImagePickerController；Info.plist 有相机/照片库隐私描述；异步图片/视频加载有加载状态；大图显示前用 CGImageSource 降采样；相机会话在后台线程启动并在 onDisappear 停止；权限拒绝时提供设置深链；AVCaptureSession 由 model 持有而不是在 UIViewRepresentable 内创建；媒体资产类型和 picker 结果跨并发边界时满足 Sendable。
30. 参考完整模式：picker recipes 见 references/photokit-patterns.md；AVCaptureSession 见 references/camera-capture.md；AsyncImage、缓存、降采样见 references/image-loading-caching.md；AVPlayer、流媒体、音频见 references/av-playback.md。

适用边界 · 注意事项

• 非 iOS/Swift 项目，或没有 PhotoKit/AVFoundation 的平台不适用。
• 目标系统低于 iOS 16 且不能使用兼容 API 时，PhotosPicker 等模式不适用。
• 不涉及用户照片库、相机采集、媒体权限或大图显示时，不应为了套用模式而引入权限和采集会话。