求助：CTkButton启动时无法显示图片，切换外观模式后恢复正常

问题概述 #

使用CustomTkinter的CTkButton组件时，给按钮分配PNG格式图片后，程序启动初期图片完全无法显示；只有调用customtkinter.set_appearance_mode()切换Light或Dark模式后，图片才会正常加载并显示。

问题复现代码 #

import customtkinter as ctk
import json

# 加载配置文件
with open("Configuration.json", "r") as config_file:
    app_config = json.load(config_file)

# 初始设置外观模式为系统默认
ctk.set_appearance_mode("System")
ctk.set_default_color_theme("blue")

# 创建主窗口
root = ctk.CTk()
root.geometry("400x300")
root.title("CTkButton Image Test")

# 创建带图片的按钮（初始不显示图片）
icon_image = ctk.CTkImage(
    light_image=ctk.CTkImage.load(app_config["icon_path"]),
    dark_image=ctk.CTkImage.load(app_config["icon_path"])
)
test_button = ctk.CTkButton(root, text="测试按钮", image=icon_image, compound="left")
test_button.pack(pady=30)

# 切换外观模式的按钮
def switch_appearance_mode():
    current_mode = ctk.get_appearance_mode()
    new_mode = "Dark" if current_mode == "Light" else "Light"
    ctk.set_appearance_mode(new_mode)

mode_switch_btn = ctk.CTkButton(root, text="切换外观模式", command=switch_appearance_mode)
mode_switch_btn.pack(pady=10)

root.mainloop()

Configuration.json 配置文件 #

{
    "icon_path": "test_icon.png"
}

解决方案 #

这个问题的核心原因是CTkImage初始化时，当前外观模式的渲染上下文未完全建立，导致图像无法正确绘制。以下是几种可靠的解决方法：

1. 延迟初始化按钮到窗口空闲状态 #

利用窗口的after_idle事件，在主窗口完成初始化后再创建带图片的按钮，确保外观模式的渲染环境已经就绪：

def init_image_button():
    icon_image = ctk.CTkImage(
        light_image=ctk.CTkImage.load(app_config["icon_path"]),
        dark_image=ctk.CTkImage.load(app_config["icon_path"])
    )
    test_button = ctk.CTkButton(root, text="测试按钮", image=icon_image, compound="left")
    test_button.pack(pady=30)

# 窗口空闲时执行按钮初始化
root.after_idle(init_image_button)

2. 显式指定图像尺寸并强制刷新 #

在创建CTkImage时显式指定尺寸，同时在按钮创建后手动触发组件刷新，确保图像被正确渲染：

icon_image = ctk.CTkImage(
    light_image=ctk.CTkImage.load(app_config["icon_path"]),
    dark_image=ctk.CTkImage.load(app_config["icon_path"]),
    size=(24, 24)  # 根据按钮大小调整合适的尺寸
)
test_button = ctk.CTkButton(root, text="测试按钮", image=icon_image, compound="left")
test_button.pack(pady=30)
test_button.update_idletasks()  # 强制刷新组件

3. 升级CustomTkinter到最新版本 #

部分旧版本的CustomTkinter存在外观模式切换时的图像渲染bug，升级到最新版本可以直接解决这类问题：

pip install --upgrade customtkinter

额外注意事项 #

• 确认PNG图片路径正确，避免相对路径错误导致图像加载失败；
• 如果图片尺寸过大，会被CTkButton自动缩放，建议提前调整到合适尺寸以优化渲染效果。

内容的提问来源于stack exchange，提问作者Jan Vaško