企业官网建设流程全解析

换主题色这件事，很多人在 QSS 上折腾得挺顺，按钮底色、边框、文字颜色一条条改过去都生效了，结果一抬头发现工具栏里那排图标还是硬邦邦的深灰，跟新配色放在一起像贴错了标签。我前后在三个桌面项目里踩过这个坑，最早的做法是给每个主题各准备一套 SVG 静态资源，浅色主题一套深图标、深色主题一套浅图标，维护起来极其痛苦——加一个图标要画两遍，改一次命名要同步两个目录，主题一多直接把资源目录撑成灾难现场。后来才认真去啃 Qt-Material 这套图标资源系统的实现，把 SVG 图标动态颜色替换这件事彻底做通。这篇就聊透这条路：SVG 文件本身没有"颜色变量"这种东西，那我们到底是在哪一层把颜色塞进去的，Qt-Material 的资源是怎么组织的，几种换色路线各自的天花板在哪，以及我实测中反复撞到的那些坑。

1. 图标颜色被写死的三个层级

1.1 颜色在渲染链路中的注入点

要搞清楚 SVG 换色，先得把"一个图标从文件变成屏幕上那几个像素"这条链路拆开。链路大致是：磁盘上的 .svg 文本 → XML 解析器读成节点树 → 渲染器把节点树转成绘制指令（填充路径、描边路径）→ 绘制指令里的颜色值参与光栅化 → 得到带 alpha 通道的位图 → 位图被 QIcon 包一层 → 控件拿去绘制。

颜色真正被"写死"的位置在第四步，也就是绘制指令执行的时候，fill或stroke里那个具体的色值。这意味着我们其实有三个可以下手的地方：一是在文本层动手，把 SVG 源文件里的色值改掉再交给渲染器；二是在光栅化之后动手，把它当成一张 alpha 蒙版重新上色；三是在 QIcon 这一层动手，通过自定义图标引擎在取图时动态着色。三条路都通，代价完全不同。

关键在于，很多人第一反应是去改 QSS 里的color，幻想图标能像文字一样跟着前景色走。这条路走不通，因为 QSS 的color只作用于文字绘制和qproperty-之类的属性，图标要么走image:/background-image:，要么走setIcon()，前者走的是样式表图片加载器，后者走 QIcon 的绘制，两者都不会去读color。所以别在这上面浪费时间了，我第一次就是在这儿耗了半个下午。

1.2 QIcon 的状态机里根本没有"颜色"这个维度

再往深一层说，QIcon 内部是个状态机：Normal、Disabled、Active、Selected 四种模式，On/Off 两种状态，一共组合出若干种变体，每种变体对应一组不同尺寸的位图。它管的是"什么状态下用哪张图"，从头到尾没有"颜色"这个维度。

这解释了一个常见困惑：为什么我给按钮setEnabled(False)之后图标会自动变灰？不是 Qt 帮你换了个颜色，而是 QIcon 在 Disabled 模式下会去找对应的灰化版本，找不到时就用引擎自己生成一个降饱和的近似版本。也就是说，QIcon 层面的"变色"只有降饱和这一种，而且完全不可控——你想让它变成某个具体的主题色，它做不到。

所以在 Qt-Material 这类主题库里，图标颜色必须是主题系统自己管起来的，因为它要的不只是"深色浅色两个版本"，而是任意主题色板下的任意色值。这就决定了必须有自己的一套图标提供者，而不能指望 QIcon 原生能力。

1.3 单色约定是整套方案成立的前提

这里有个前置约定必须先摆出来：动态换色只对单色图标成立。一个图标里如果有红绿蓝三种颜色（比如某些品牌 logo 或者彩色状态图标），你把它整体染成主题色，等于把所有语义信息抹掉了。

Qt-Material 的图标集基本遵循 Material Design 的单色填充风格，路径里通常只有一个色值，或者干脆全黑由外部决定，这就是为什么它能做全局换色。我自己的项目里也沿用了这个约定：通用界面图标一律单色，需要彩色的场景（比如状态指示灯）单独走一套不走换色流程的目录。这个约定看似是限制，实际上是省钱——后面所有的缓存、索引、失效逻辑都建立在它之上。

我在第二个项目里就犯过没定约定的错，混进去几个多色图标，结果换色逻辑一跑，指示灯全变成同一个色，排查了半天才发现是染色逻辑无差别地把所有 fill 都改了。后来加了白名单，只有登记在案的图标才参与染色。

2. Qt-Material 图标资源的组织方式

2.1 目录布局与命名约定

Qt-Material 这个库的图标资源一般放在包的resources/icons目录下，按语义分类分子目录，比如导航类、操作类、状态类，文件名用下划线或连字符风格的小写词组，比如arrow_back、content_copy、delete_outline这种。命名统一的意义不只是好看，而是让"图标名"能直接作为缓存的 key 使用——调用方只需要给一个字符串content_copy，提供者就能拼出路径、拼出缓存 key、拼出资源别名。

我在自己的项目里把这个约定又收紧了一层：文件名必须和逻辑名完全一致，不允许别名映射表。因为一旦有了别名，缓存 key 到底用哪个、主题文件里引用哪个、设计师交付时按哪个命名，三套标准就开始打架了。宁可改名一次，也不要维护映射。

路径解析这块，实践中我推荐两种方案：一是直接走文件系统，从资源根的绝对路径拼；二是把整套 SVG 编进 Qt 的.qrc资源文件，用:/icons/xxx.svg访问。前者方便热更新、方便设计师交付时直接丢文件进去；后者打包省心、路径不依赖工作目录。Qt-Material 默认走的是文件路径方案，因为它的主题 xml 和应用是两个独立产物，路径通过包内相对位置推导。如果你的应用要打包成单文件分发，我建议还是编进 qrc，能省掉一堆"相对路径在打包后失效"的破事。

提示：把图标编进 qrc 之后，文件系统路径就失效了。如果你的换色逻辑里涉及"读源文件文本"，必须改成QFile(":/...")读取，不能直接用 Python 的open()，否则会抛"文件不存在"，而这个错误在开发机上往往不出现，只在打包后炸。

2.2 图标名到实际路径的解析

解析过程本身就三步：拿到逻辑名，判断扩展名，拼路径。听起来没什么好说的，但坑全在细节里。比如逻辑名带不带扩展名？如果调用方传了content_copy.svg，你拼出来就变成content_copy.svg.svg。我在两个不同的库里都见过这个 bug，表现是某些图标出来某些不出来，因为恰好有一批调用点了带扩展名的写法。

稳妥的写法是先做归一化：剥掉扩展名，统一小写，把连字符和下划线统一成同一种。然后再拼。归一化这一步还有额外好处——设计交付的文件名经常是Content-Copy.svg这种驼峰加连字符的混合体，归一化之后就不用挨个改名了。

判断图标是否存在的逻辑也要注意，不要用"能不能打开文件"来判断，因为打开文件会真的触发一次 IO。我一般是在初始化时把整个图标目录扫一遍，建一个set存所有可用名字，判断存在性直接查集合。这个集合还能顺手用来做开发期的断言——谁传了一个不存在的图标名，直接 log 一条警告，比默默返回一个空图标强一万倍。我用这个办法在开发期揪出过十几个拼错的图标名。

2.3 主题色板里到底取哪个字段

颜色从哪来？Qt-Material 的主题文件（xml 格式）里定义了一组调色板字段，包括主色、辅色、各种层级的背景色、不同强度的前景色。图标一般跟随前景色：浅色主题下用深色前景，深色主题下用浅色前景。同时还有"强调图标"的概念，比如选中态的图标用主色，普通态用前景色。

这里有个设计选择值得说清楚：图标颜色是跟着"前景色"走还是跟着"主色"走？如果全跟主色走，界面上所有图标都变成品牌色，视觉上非常吵；如果全跟前景色走，强调态就出不来。我自己的做法是分级——默认态跟前景色，选中/悬停态跟主色，禁用态跟前景色的低透明度变体。这套分级对应到代码里就是调用方显式传颜色，而不是让提供者自己去猜上下文。

也就是说，图标提供者不应该自己做"这个图标该用什么色"的判断，它只负责"给我名字和颜色，我还你一张图"。上下文判断交给调用方或者交给一层薄薄的封装。这个职责划分让我在后面做缓存和主题热切换的时候省了很多事，因为缓存 key 只需要颜色值本身，不需要携带"当前是选中态还是普通态"这种语义信息。

3. 三条换色路线的横向对比

3.1 三种方案的成本与收益

先上一张表，把三条路的核心差异摆清楚，后面再逐条展开实现细节。

选型上我的一般结论是：如果你的图标集是纯单色的、需要跟随主题频繁换色，走蒙版着色；如果图标里有多色或者需要保留描边细节，走文本重写；只有在需要精细控制 QIcon 各状态变体（比如选中态要加背景圈）时才上自定义引擎，因为它的维护成本明显高一个量级。

3.2 文本重写路线的适用边界

文本重写的本质是"在渲染前先改源"。优点是它保留了 SVG 的全部表达能力，渐变色、描边、透明遮罩、多色路径全都不受影响，因为你只动了颜色值，没动结构。缺点也很明显：每次换色都要重新解析一遍 XML，如果界面上有几十个图标，主题切换瞬间就会有一波解析开销；而且一旦涉及写临时文件，就要处理文件名冲突、清理时机、并发写这些琐碎问题。

我在一个需要保留渐变描边的项目里用了这条路。那个项目的图标是设计师手工画的，路径上有线性渐变，蒙版着色会把渐变整体压平成一个纯色，视觉上完全垮掉。所以只能老老实实改源。改源的实现细节我后面单独讲，里面有几个必须处理的分支。

3.3 蒙版着色的核心思想

蒙版着色的思路特别朴素：先把 SVG 渲染成一张只有透明度的图——所有不透明像素都是同一种颜色（通常是黑或白都无所谓），透明度形状就是图标形状；然后把这张图当成蒙版，用目标颜色整体填一遍，只填在蒙版不透明的地方。这样出来的结果就是形状不变、颜色变成目标色、边缘的半透明像素也被正确保留成半透明的目标色。

Qt 里做这件事靠QPainter.CompositionMode_SourceIn：这个合成模式的含义是"用源颜色乘以目标 alpha"，也就是画笔涂的颜色只在目标已有内容的位置生效，并且按目标 alpha 加权。所以顺序必须是先画图、后填色，反过来就是一张纯色方块。

这个方案的性能非常好，因为渲染一次就够，填色是一次全矩形操作，GPU 加速下几乎不要钱。它的天花板在于不支持多色，以及必须处理好尺寸和 DPR，否则边缘会糊。

4. 文本重写路线的落地细节

4.1 用 ElementTree 而不是正则表达式

我见过太多人用正则去替换 SVG 里的颜色，比如re.sub(r'fill="#[0-9a-fA-F]{3,6}"', ...)。这个写法能跑通 demo，但上生产必炸，原因有三个：一是漏掉style="fill:#000"这种内联样式写法；二是误伤fill="none"，一个靠描边画的图标被填成实心块；三是不认识fill="currentColor"这种语义写法。

正确做法是用 XML 解析器。Python 标准库的ElementTree够用，先注册命名空间避免序列化时冒出ns0:前缀：

import xml.etree.ElementTree as ET SVG_NS = "http://www.w3.org/2000/svg" ET.register_namespace("", SVG_NS) ET.register_namespace("xlink", "http://www.w3.org/1999/xlink") def rewrite_svg_color(svg_path: str, hex_color: str) -> bytes: tree = ET.parse(svg_path) root = tree.getroot() _apply_color(root, hex_color) return ET.tostring(root, encoding="utf-8", xml_declaration=True) def _apply_color(node, hex_color: str): fill = node.get("fill") style = node.get("style") if fill is not None and fill.lower() not in ("none", "transparent", "url(#none)"): node.set("fill", hex_color) if style and "fill:" in style.replace(" ", ""): parts = [p for p in style.split(";") if p.strip()] new_parts = [] for p in parts: if p.strip().startswith("fill:") and "none" not in p.lower(): new_parts.append(f"fill:{hex_color}") else: new_parts.append(p) node.set("style", ";".join(new_parts)) for child in list(node): _apply_color(child, hex_color)

这段代码的关键在几个判断分支。fill="none"必须跳过，否则描边式图标会被填实。url(#gradient)形式的引用也要跳过，因为那是渐变引用不是颜色值，直接覆盖会让渐变失效。currentColor这种语义值反而可以放心覆盖，因为它就是留给外部指定颜色的占位符。

4.2 fill 继承与父节点染色

SVG 的fill是继承属性。如果父节点<g fill="#000000">上写了颜色，子节点<path>上什么都没写，那子节点实际是用父节点的颜色。这时候如果你只遍历到子节点去改，会发现改了个寂寞——子节点本来就没 fill 属性，你也没给父节点改，颜色纹丝不动。

我的处理是加一条规则：如果当前节点没有 fill 但父节点有，就在当前节点上显式补一个 fill。这样虽然会让 SVG 文件变大（多了一些冗余属性），但保证每个可视节点都带着明确颜色，后续替换逻辑简单得多。另一种做法是直接改父节点，让继承生效，代码更短，但风险是如果父节点下混了不该染色的子节点就一起被改了。我倾向显式补齐，用空间换确定性。

还有个反向问题：如果某个子节点本来就想保持不同颜色（多色图标），显式补齐会把它也统一了。所以这条路线实际上也默认单色。真要做多色精确替换，得按节点 id 或者路径特征打标记，那是另一套工程量，超出了日常需求的范畴。

4.3 临时文件的生成与回收

改完的 SVG 字节流必须落地成文件才能交给QSvgRenderer，因为它是按路径加载的。落地就有命名问题：同一个图标在不同主题下要生成不同文件，文件名必须带上颜色或者哈希。我用的是"图标名 + 颜色十六进制 + 短哈希"的格式，放在系统临时目录下的固定子目录里。

回收策略上，我试过两种。一种是启动时清空整个临时子目录，简单粗暴，但多实例运行时会把别的实例正在用的文件删掉——如果你的应用允许开多个窗口进程，这就会偶发白图。另一种是懒清理，每个文件记一个最后访问时间，超过阈值才删。我最后用的是第二种，配一个简单的定时器，每十分钟扫一次，删掉半小时没碰过的。

注意：临时文件目录一定要用tempfile.gettempdir()起头，别自己拼相对路径。我见过有实现把临时 SVG 写到当前工作目录下，结果用户从快捷方式启动时工作目录是系统目录，直接权限报错，整个图标系统哑火。

5. 蒙版着色：SourceIn 的正确打开方式

5.1 先透明底再渲染，顺序不能反

蒙版着色的完整流程我写成下面这个函数，这是我在项目里反复验证过的版本：

from PySide6.QtCore import QSize, QRect, QRectF, Qt from PySide6.QtGui import QImage, QPainter, QPixmap, QColor from PySide6.QtSvg import QSvgRenderer def render_tinted_svg(svg_path: str, size: QSize, color: QColor, dpr: float = 1.0) -> QPixmap: renderer = QSvgRenderer(svg_path) px_w = max(1, int(round(size.width() * dpr))) px_h = max(1, int(round(size.height() * dpr))) image = QImage(px_w, px_h, QImage.Format_ARGB32_Premultiplied) image.fill(Qt.transparent) painter = QPainter(image) painter.setRenderHint(QPainter.Antialiasing, True) painter.setRenderHint(QPainter.SmoothPixmapTransform, True) renderer.render(painter, QRectF(0, 0, px_w, px_h)) painter.setCompositionMode(QPainter.CompositionMode_SourceIn) painter.fillRect(QRect(0, 0, px_w, px_h), color) painter.end() pixmap = QPixmap.fromImage(image) pixmap.setDevicePixelRatio(dpr) return pixmap

这里有三个顺序上的硬要求。第一，image.fill(Qt.transparent)必须在前，因为QImage新建时内容是未初始化的脏数据，不填透明你会拿到一堆随机彩色噪点——我第一次跑的时候屏幕上出现了一坨花屏，还以为是渲染器炸了。第二，setCompositionMode必须在render()之后调用，先设合成模式再渲染会导致渲染结果本身就被 SourceIn 处理，出来是空白。第三，painter.end()必须在QPixmap.fromImage之前，否则有些平台上图像还没写完就被拷走了，偶发缺一块。

5.2 高 DPI 下的尺寸与 DPR 计算

高 DPI 是这条路最容易出错的地方。核心原则是：像素尺寸按逻辑尺寸 × DPR算，画的时候按像素尺寸铺满，最后把devicePixelRatio设回 DPR。这样 Qt 在绘制到控件上时会自动按 DPR 缩放，物理像素正好一一对应，不会糊。

如果你偷懒不乘 DPR，直接按逻辑尺寸渲染，那么在 2 倍屏上这个位图会被拉大两倍显示，边缘就糊了。反过来如果渲染了像素尺寸但忘了setDevicePixelRatio，那图标会显示成预期大小的两倍——因为 Qt 把像素尺寸当逻辑尺寸用了。这两个错误表现截然不同：前者糊，后者大。记住这个对应关系，排查的时候一眼就能定位。

DPR 从哪拿？QGuiApplication.primaryScreen().devicePixelRatio()拿的是主屏的，多屏环境下不同屏幕 DPR 可能不同。严谨做法是用QWidget.devicePixelRatioF()，但图标提供者通常拿不到控件。我的折中是取所有屏幕 DPR 的最大值来生成位图，配合QPixmap.setDevicePixelRatio让 Qt 自己缩放。代价是 1 倍屏上会多占一点内存，但换来了跨屏拖动时不糊。

5.3 边缘发虚与锯齿的两个来源

实测下来，蒙版着色出现的边缘质量问题基本来自两处。

第一处是 SVG 本身在渲染时没开抗锯齿。上面代码里的Antialiasing和SmoothPixmapTransform两个 hint 都要开，前者管路径边缘，后者管位图缩放。只在部分路径上开是没用的，必须两个都开。

第二处是渲染尺寸和显示尺寸不匹配。比如你按 24×24 生成位图，控件却按 32×32 绘制，Qt 就会拉伸这张位图，边缘必然糊。解决办法是让图标提供者能感知目标尺寸：QIcon.pixmap(size)会把请求尺寸传进来，自定义引擎可以在这里按需生成对应尺寸，而不是死磕一个固定尺寸。

我早期做过一个特别蠢的优化：所有图标统一按 64×64 渲染，然后靠缩放复用。省是省了渲染次数，但 16×16 的小图标缩下来线条全糊成一团，观感极差。后来改成按请求尺寸渲染并缓存，命中率其实很高，因为同一类控件的图标尺寸是固定的，实际只会用两三种尺寸。

6. 主题热切换时的颜色联动机制

6.1 缓存键必须包含哪些维度

一旦上了缓存，颜色就必须进 key，否则换主题之后拿到的还是旧颜色的图。我的 key 是四元组：(图标逻辑名, 颜色 rgba 整数, 宽, 高)，再加上 DPR 作为第五维。

为什么颜色要用 rgba 整数而不是 QColor 对象？因为 QColor 作为字典 key 时依赖 hash 实现，跨版本行为不完全一致，而且 QColor 可变，理论上可以被原地修改导致哈希失效。转成整数最保险。同理尺寸用两个 int 而不是 QSize。

DPR 进 key 这一点很关键。如果用户把窗口从笔记本屏拖到外接显示器，DPR 从 1 变成 2，不重新生成的话图标会突然变糊。把 DPR 纳入 key 之后，新请求自然 miss，重新生成一版高分辨率图，这个过程是透明的。

6.2 谁负责触发失效

主题切换之后，缓存里的旧图必须整体作废，不然会有一批图标还挂着上个主题的颜色。触发点应该只有一个：主题应用完成的那一刻。Qt-Material 的应用主题流程是解析 xml、生成 QSS、app.setStyleSheet()。在setStyleSheet之后、界面重绘之前，是清理缓存的正确时机。

我把它做成了一个信号：图标提供者暴露themeChanged信号，setStyleSheet完成之后 emit 一次，所有持有图标的控件连到这个信号上重新setIcon()。这样责任链很清晰，不需要谁去猜"主题是不是变了"。

有个细节要注意：信号发出时不要立刻清空缓存然后同步重建，那会在主线程上产生一次明显的卡顿，主题切换动画会卡一下。我的做法是清空缓存 + 标记一个脏位，然后靠控件的重绘请求自然驱动重建。因为重绘是分帧发生的，重建也就被摊薄了，用户感知不到卡顿。

6.3 已经贴到控件上的图标怎么更新

这是最容易漏的一环。缓存清了、信号发了，但QPushButton.setIcon()已经把旧 QPixmap 塞进按钮内部了，按钮不会主动去问"你有没有新图"。所以必须有一批"订阅者"在主题变化时重新调用setIcon。

QAction的情况好一些：如果把图标设在 QAction 上，工具栏和菜单里的关联控件会自动跟随 QAction 的图标变化更新，这是 Qt 内置的联动。所以凡是能用 QAction 的地方尽量用 QAction，能省掉一大堆手动刷新。

对于直接setIcon的普通按钮，我维护了一个弱引用列表，注册时登记，注销时清理，收到主题信号就遍历重设。用weakref.ref是为了防止控件销毁后列表里留着悬空引用——不用弱引用的话，关闭对话框之后那个列表还会拽着已销毁的控件不放，触发一次主题切换就是一片报错。

import weakref class IconBinder: def __init__(self, provider): self._provider = provider self._refs = [] provider.themeChanged.connect(self._refresh) def bind(self, widget, icon_name, role="normal"): self._refs.append((weakref.ref(widget), icon_name, role)) widget.setIcon(self._provider.icon(icon_name, role)) def _refresh(self): alive = [] for ref, name, role in self._refs: w = ref() if w is None: continue w.setIcon(self._provider.icon(name, role)) alive.append((ref, name, role)) self._refs = alive

这段代码平时看着多余，但主题一切换、界面上几十个按钮同时更新的时候，它比手动挨个找控件靠谱得多。

7. 实测排错：五个反复出现的现象

7.1 图标渲染成纯黑方块

这个是出现频率最高的。原因基本锁定在合成模式上：在render()之前就调了setCompositionMode(SourceIn)，导致整个渲染过程都在做 alpha 相乘，最终结果被涂成一整块。

还有一种可能是QImage没填透明，渲染器画上去的东西叠在脏数据上，alpha 全是 255，于是整块不透明，填色之后就是纯色方块。这两种情况的区别是前者连形状都没有，后者至少能看出一点轮廓残影。

排查方法很直接：把中间那张QImage直接save()到临时文件看一眼。如果存出来是纯色，问题在渲染；如果存出来是对的、贴到控件上才变方块，问题在 QPixmap 转换或者控件绘制那一侧。分两步走，能立刻缩小范围。

7.2 高 DPI 下图标突然变大

前面提过，这是漏了setDevicePixelRatio。表现是图标尺寸正好是预期的 DPR 倍——2 倍屏上图标大一倍，非常明显，一眼就能确认。

反向的情况是设了 DPR 但像素尺寸没乘，图标尺寸是对的但模糊。这两个症状可以快速区分：尺寸对但糊 → 尺寸算错；尺寸大但清晰 → DPR 没设。我把这条写在了团队的问题排查清单里，能省掉很多来回。

7.3 禁用态颜色不生效

给按钮设成禁用之后，图标颜色没按预期变淡，而是变成了 Qt 自动生成的降饱和版本。原因是setEnabled(False)之后，QIcon 会切到 Disabled 模式去取图，而你的自定义引擎或者提供者只处理了 Normal 模式的 pixmap 请求，Disabled 请求走了默认逻辑。

解决办法是在自定义引擎的pixmap(mode, state, size, scale)里显式判断 mode：Disabled 时用低透明度的目标色重新生成一张，而不是让基类去降饱和。这个细节如果不在引擎里处理，只靠外层的setIcon是管不到的，因为 QIcon 内部的模式切换是它自己做的。

7.4 图标边缘出现彩色毛边

这个现象在深色主题下特别明显：明明是纯白图标，边缘却有一圈偏青或偏紫的细线。根源是QImage.Format_ARGB32_Premultiplied之外用了非预乘格式，或者在填色时用了带 alpha 的颜色导致边缘像素的 alpha 被二次相乘。

CompositionMode_SourceIn的语义是源颜色乘以目标 alpha。如果源颜色自身还带 alpha（比如QColor(255,255,255,200)），边缘像素会被乘两次，alpha 通道不连续，就会出现毛边。所以填色时用的 QColor 应该是不透明的，需要透明效果就整体调setOpacity，不要在颜色里带 alpha。

7.5 启动变慢与内存膨胀

一开始我把所有图标在启动时预生成了一遍，图省事。结果是冷启动多了 300 多毫秒，内存多占了小几十兆——因为每个图标都生成了多尺寸、多状态的位图。后来改成懒加载 + 上限 512 条的 LRU，冷启动回到原来水平，内存也稳定了。

LRU 的实现不需要引第三方库，collections.OrderedDict配合move_to_end就够。淘汰时记得调pixmap的释放——Python 里交给 GC 就行，但如果你的引擎里有 C++ 侧持有的对象，需要显式断开。

from collections import OrderedDict class IconCache: def __init__(self, cap=512): self._cap = cap self._data = OrderedDict() def get(self, key): if key in self._data: self._data.move_to_end(key) return self._data[key] return None def put(self, key, value): self._data[key] = value self._data.move_to_end(key) while len(self._data) > self._cap: self._data.popitem(last=False) def clear(self): self._data.clear()

上限设多少合适？我的经验是按"图标总数 × 3"估。因为实际用到的尺寸组合一般不超过三种，超过这个数说明调用方在乱传尺寸，那该修的是调用方而不是把缓存调大。

8. 把这套东西做成可复用的基础设施

8.1 提供者接口应该长什么样

折腾到第三个项目，我把这套逻辑收敛成了一个很小的接口：icon(name, role) -> QIcon、pixmap(name, role, size) -> QPixmap、themeChanged信号、clearCache()。就这四个。

role是语义角色而不是具体颜色，比如normal、primary、disabled、danger，由提供者内部根据当前主题去映射成实际色值。这样做的好处是调用方完全不需要知道当前主题色是什么，换主题时它们什么都不用改，只要响应themeChanged重新拿一次图标就行。

把颜色映射放在提供者内部还有一个隐蔽的好处：主题色板里"前景色"不一定适合直接当图标色。浅色主题的纯黑图标放在浅灰背景上会显得脏，通常要取一个略淡的前景色。这种微调属于主题适配范畴，藏在提供者里最合适，暴露给调用方只会制造不一致。

8.2 打包与分发的注意事项

如果走 qrc 资源方案，换色逻辑读文件时必须用QFile而不是open()。这一点前面提过，但值得再强调一次，因为它是最典型的"开发环境正常、打包后全白"的问题。判断方法很简单：如果你的程序在打包后所有图标都消失了，第一反应就该去查资源路径和读取方式。

另一个坑是 SVG 依赖的字体。有些图标里嵌了<text>元素依赖特定字体渲染，打包之后字体没带进去，图标就变成空白或者方块。Qt-Material 的图标集一般不用文本元素，但如果你混入了自己画的图标，要留意这一条。我遇到过的一个案例是某个图标里有个小圆点是用 text 画的句号，打包后那个点消失了，查了很久才发现是字体问题。

8.3 什么时候该放弃动态换色

最后说个反向建议：不是所有图标都需要动态换色。有些图标本身就带语义色，比如警告用黄、成功用绿、错误用红，这些颜色不应该跟随主题变，变了反而让人误读。这类图标应该走"固定色"通道，不参与染色流程。

我在项目里做了两条通道：icon()走动态染色，rawIcon()直接返回原图。哪些走哪条由图标名决定，而不是调用时传参决定——传参决定的话，不同调用方对同一个图标用不同通道，视觉上就不一致了。这个判断放在提供者内部，统一而稳定。

判断标准其实很简单：这个图标的颜色是否携带信息？如果颜色变了意思也变了，就别染；如果颜色只是装饰，那就染。用这条标准过一遍图标集，通常会发现有六七个不该染色的，把它们踢出流程，后面的问题会少一大截。

我在实际操作里的体会是，SVG 动态换色这件事真正的难点不在渲染，而在资源组织、缓存设计和主题联动的边界划分。渲染那几十行代码一晚上就能调通，但如果没有把缓存 key 设计好、没有想清楚谁负责触发失效、没有把"哪些图标不该染色"这条线划出来，后面每加一个功能都会在这个基础上再长一个坑。我现在的新项目基本都是先把这套提供者骨架搭好，再往里填界面，比事后补要省心得多。