通过代码设置UIButton背景图片不生效该如何解决？

AI 小北

2026-9-27

问题原因

你遇到的是iOS 15及以上系统UIButton新式配置样式的兼容问题，Storyboard中默认创建的UIButton采用Plain样式，该样式下系统优先使用UIButton.Configuration的背景配置，直接调用setBackgroundImage(_:for:)方法会被默认配置覆盖导致不生效。

解决方法

你可以任选以下任一方案解决：

方案1：修改Storyboard按钮样式
在你提供的按钮属性设置面板中，将Style选项从默认的Plain修改为Custom，修改后你现有的代码即可正常运行，背景图会正常显示。

方案2：代码适配新式Configuration样式
如果你需要保留UIButton的新式样式特性，可通过configuration属性设置背景图，修改后的代码如下：

import UIKit

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        // 加上alwaysOriginal强制使用原图渲染，避免被按钮tint色覆盖
        let imageToSet = UIImage(named: "3-1")?.withRenderingMode(.alwaysOriginal)
        
        if #available(iOS 15.0, *) {
            var config = b1.configuration ?? UIButton.Configuration.plain()
            config.background.image = imageToSet
            b1.configuration = config
        } else {
            b1.setBackgroundImage(imageToSet, for: .normal)
        }
        
        imageView.image = imageToSet
    }

    @IBOutlet weak var b1: UIButton!
    @IBOutlet weak var imageView: UIImageView!
}