iOS UIImageView 設置圖片失效？常見原因與解決方案

問題現象

許多 iOS 初學者會遇到這種情況：在 Storyboard 中為 UIImageView 設置 image 屬性選擇 lenna.png 時圖片正常顯示，但改用代碼 self.imgView.image = [UIImage imageNamed:@"lenna.png"]; 卻顯示空白。

核心排查清單

1. 圖片資源是否正確加入專案

• 確認 lenna.png 實際存在於專案的 Assets.xcassets 或 Bundle Resources 中。
• 檢查 Target Membership 是否勾選了當前 Target。
• 注意大小寫：iOS 真機文件系統區分大小寫，模擬器不區分。

2. 圖片名稱拼寫與後綴

// 推薦寫法：PNG 可省略後綴
[UIImage imageNamed:@"lenna"]; 

// JPG 或其他格式必須帶後綴
[UIImage imageNamed:@"photo.jpg"];

3. Outlet 連接是否有效

• 打開 Assistant Editor，檢查 @property (weak, nonatomic) IBOutlet UIImageView *imgView; 左側圓點是否實心（表示已連接）。
• 若曾刪除重連，舊連接可能殘留導致 imgView 為 nil，發送消息無效。

4. 代碼執行時機與線程

• 確保代碼在主線程執行（UI 更新必須在主線程）。
• 若在 viewDidLoad 中設置，確認 imgView 已加載完成（Storyboard/XIB 加載時會自動連接）。

5. 圖片尺寸與顯示模式

• 若圖片極大超出螢幕，可能顯示在可視區域外。設置 imgView.contentMode = UIViewContentModeScaleAspectFit; 適配。
• 檢查 imgView.hidden 或 alpha 是否被誤設置。

快速調試技巧

// 1. 斷點檢查對象是否為 nil
NSLog(@"imgView: %@", self.imgView);
NSLog(@"image: %@", [UIImage imageNamed:@"lenna"]);

// 2. 嘗試直接用 imageWithContentsOfFile 排除緩存問題
NSString *path = [[NSBundle mainBundle] pathForResource:@"lenna" ofType:@"png"];
UIImage *img = [UIImage imageWithContentsOfFile:path];
self.imgView.image = img;

總結

90% 的情況是 資源未正確添加、名稱大小寫不匹配 或 Outlet 斷連。按清單逐項排查通常能秒解。