CustomTkinter需用CTk类替代Tk类初始化，混用原生组件会导致样式断裂；CTkButton绑定command要防事件参数传递；布局须统一用grid或pack；主题切换需同步设置外观模式与颜色主题。
CustomTkinter 不是“换肤”工具，它是一套从头设计的现代控件库，直接替换 tkinter 原生组件才能获得真正扁平化效果——硬套原生 Tk 或混用 ttk 会导致样式断裂、事件失效、主题无法同步。
初始化时必须用 CTk 替代 Tk
这是最常被跳过的一步。哪怕只改一行，漏掉就会让整个窗口失去暗色模式支持、圆角、阴影和字体缩放能力。
-
import customtkinter as ctk后，必须写root = ctk.CTk()，不能写tk.Tk()或ctk.Tk()（后者已废弃） - 如果用了
ctk.set_appearance_mode("dark")，但窗口仍是白底，大概率是用了错的根窗口类 - 子窗口（如
CTkToplevel）也需显式继承自ctk类，不能用tk.Toplevel
CTkButton 的 command 绑定要防空参调用
原生 Button 允许 command=lambda: func() 这种写法，但 CTkButton 在某些版本中会把点击事件对象（event）自动传入，导致 func() 报 TypeError: func() takes 0 positional arguments but 1 was given。
- 稳妥写法：始终显式丢弃参数，比如
command=lambda e=None: do_something() - 或者改用普通函数绑定：
button.configure(command=do_something)（前提是该函数不依赖事件参数） - 若需事件信息（如鼠标坐标），函数签名必须为
def handler(event):，且绑定时不要加lambda
布局别碰 pack() 和 grid() 混用
CustomTkinter 对布局管理器没有额外封装，但它的控件默认 padding、margin、最小尺寸都比原生大，混用 pack() 和 grid() 在同一父容器里极易触发 RuntimeError: cannot use geometry manager，而且错误堆栈不提示具体哪行。
- 一个容器内只选一种：要么全用
grid(row=..., column=...)，要么全用pack(side=...) - 推荐优先用
grid()，因为CTkFrame的columnconfigure/rowconfigure配合sticky更容易实现响应式拉伸 - 如果要用
place()，注意CTk控件的width/height是建议值，实际尺寸受主题字体、缩放因子影响，别硬写死像素值
主题切换后字体/尺寸没变？检查 ctk.set_default_color_theme() 调用时机
颜色主题（blue、green、dark-blue）和外观模式（light/dark）是两个独立维度。只调 set_appearance_mode 不会重载按钮颜色、输入框边框色等；反之，只换 color theme 也不影响背景明暗。
-
ctk.set_default_color_theme("dark-blue")必须在CTk()实例化之前调用，否则新窗口不会生效 - 动态切换主题需同时调用两者：
ctk.set_appearance_mode("light")+ctk.set_default_color_theme("blue") - 自定义主题文件路径必须是 .json，且字段名严格匹配（如
"CTkButton": {"fg_color": ["#3B8ED0", "#1F6AA5"]}），缺一个中括号或引号都会静默失败
真正麻烦的不是写 UI，而是当 CTkComboBox 下拉项文字被截断、或 CTkScrollableFrame 滚动条卡住时，得翻 CustomTkinter 的 GitHub issues 才发现是某个小版本的 font 参数解析 bug——这类问题不会报错，只表现异常，调试成本远高于代码量本身。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
