UIImageView 图片设置没反应？别急，这份排查指南帮你快速找出原因！

在 iOS 应用开发中，UIImageView 是大家用得最多的一个界面控件，但很多开发者——尤其是刚入门的新手——经常会遇到一种情况：明明已经给 UIImageView 赋了图片，可界面上却啥也看不到。这篇文章会把 导致 UIImageView 图片显示不出来 的常见原因一条条列清楚，并配上对应的检查方法和解决办法，让你能又快又准地搞定问题。

一、先确认 UIImageView 本身有没有出现在屏幕上

这是整个排查过程中最基础也最关键的一步。

你可以给这个控件加一个背景颜色，比如这样写：

imageView.backgroundColor = .red

如果红色方块能正常显示出来，就说明这个控件已经被成功加到界面上了，那问题多半出在图片加载这一块；但如果连背景色都看不见，那就得回头看看是不是忘了把它加到父视图里，或者它的位置、宽高没设对，比如约束写错了、frame 是零之类的。

二、检查图片资源是不是真的准备好了

1. 图片有没有正确放进项目里？

如果你用的是 Assets.xcassets（这是苹果推荐的做法），请确认图片确实已经拖进了正确的资源目录里。
但如果你是 直接把图片文件拖进项目文件夹（没走 Assets），那就一定要仔细检查两件事：一是选中图片后看右边的 Target Membership 有没有勾上当前目标，二是去 Build Phases → Copy Bundle Resources 里看看这张图有没有被包含进去。

⚠️ 注意：直接放进项目的图片，在代码里用 UIImage(named:) 加载时不要带后缀名（比如 .png）。不过有些老版本的 Xcode 或者像 KSImageNamed 这类插件可能会要求你写全名字，包括扩展名。

2. 图片名字有没有打错？

真机对文件名是区分大小写的，而模拟器不区分。举个例子，你的图片实际叫 MyImage.png，但代码里写成 myimage，可能在模拟器上能跑，一上真机就变成空白。这种问题特别容易让人困惑。

为了避免手误，建议装一个 Xcode 插件，它能在你输入时自动提示可用的图片名。

3. 图片格式系统认不认？

UIImageView 支持常见的格式，比如 JPEG、PNG、静态 GIF，还有 PDF（矢量图）。只要确保你的图片没有损坏，并且是这些支持的类型就行。

三、看看代码逻辑和设置时机有没有问题

1. 是不是在合适的地方设置了图片？

比如在 UITableViewCell 或 UICollectionViewCell 里，千万别在 init 方法里就急着给 imageView 赋值，因为这时候从 xib 或 storyboard 加载的子视图可能还没准备好。
✅ 正确的做法是在 awakeFromNib() 里处理，或者写一个专门的配置方法（比如叫 configure(with:)），在外部调用时再传图片进去。

另外，如果你是从网络下载图片，记得一定要在主线程里更新界面，像这样：

DispatchQueue.main.async {
    self.imageView.image = downloadedImage
}

否则就算图片下载成功了，界面也不会刷新。

2. 有没有不小心用了别的属性？

UIImageView 显示内容靠的是 image 属性，不是 backgroundColor。
有些人可能会误以为可以用 setBackgroundImage 来设图，但那是 UIButton 的方法，用在 imageView 上当然没效果。

四、还有一些特殊情况要注意

1. 如果你用了第三方图片库（比如 SDWebImage、Kingfisher）

这时候要检查图片链接是不是有效、App 有没有开网络权限、缓存机制会不会干扰加载。可以打开库的日志功能，看看具体报了什么错。

2. 图片是不是被设成了模板模式？

在 Assets 里，如果你把某张图的 Render As 选项改成 Template Image，系统就会用 tintColor 的颜色来渲染它。如果这个 tint 颜色是透明的、白色，或者跟背景一样，看起来就像没图一样。

解决办法很简单：要么把 Render As 改回 Original Image，要么手动给 imageView 设置一个看得见的 tintColor。

五、快速自查清单 ✅

结语

其实大多数 UIImageView 图片不显示的问题，根源都在于 图片资源没放对地方 或者 控件本身没摆好位置。只要你按照上面的步骤一步步检查，基本都能很快找到原因。平时写代码的时候，注意用 Asset Catalog 管理图片、起名字别乱改大小写、在合适的时机赋值，就能避开大部分坑。