ComfyUI中文版界面乱码如何解决？

Question

问题：ComfyUI中文版界面出现乱码，菜单和节点文字显示为方框或问号，尤其在Windows系统中更为常见。该问题通常由字体缺失或系统编码不兼容导致，特别是在未正确配置中文字体路径的情况下，前端界面无法正常渲染中文字符。如何通过修改配置文件或替换支持中文的字体文件，从根本上解决ComfyUI中文界面的乱码问题？

Answer 1

ComfyUI中文界面乱码问题的深度解析与系统性解决方案

1. 问题现象与初步诊断

在使用ComfyUI中文版时，用户普遍反馈界面出现文字乱码、菜单项或节点名称显示为方框（□）或问号（？），尤其是在Windows操作系统中更为显著。该现象主要集中在前端渲染层，表现为UI组件无法正确加载和绘制中文字符。

初步排查方向包括：

• 系统是否安装了常用中文字体（如微软雅黑、思源黑体）
• ComfyUI前端资源目录中是否存在字体文件缺失
• 浏览器或Electron环境的字符编码设置是否为UTF-8
• 配置文件中字体路径是否指向有效中文字体

2. 根本原因分析：从底层机制入手

ComfyUI基于Web技术栈构建，其前端依赖HTML/CSS/JavaScript进行UI渲染。当CSS中指定的字体族（font-family）未包含可用的中文字形时，浏览器将回退至默认字体，若默认字体不支持中文，则触发“字符替换”机制，显示为方框。

核心成因可归纳为以下三类：

类别	具体表现	影响范围
字体缺失	未在custom_nodes或web\fonts目录部署中文字体	全局UI组件
路径配置错误	setting.json中fontPath指向不存在的文件	启动阶段即失效
编码不一致	Python后端输出非UTF-8编码字符串	动态内容渲染异常

3. 解决方案层级一：快速修复（适用于临时调试）

通过修改前端CSS强制指定系统级中文字体，绕过自定义字体加载逻辑：

/* 修改 web/css/comfyui.css */
body, .graph-node, .menu-item {
    font-family: "Microsoft YaHei", "SimHei", "Source Han Sans CN", sans-serif !important;
}
    

此方法无需重启服务，刷新页面即可生效，适合验证字体兼容性。

4. 解决方案层级二：持久化配置（推荐生产环境使用）

步骤如下：

1. 下载开源中文字体（如思源黑体）并转换为WOFF格式
2. 将字体文件放入ComfyUI/web/fonts/目录，例如：SourceHanSansCN-Regular.woff
3. 编辑ComfyUI/web/index.html，添加@font-face声明：

<style>
@font-face {
    font-family: 'CustomChineseFont';
    src: url('./fonts/SourceHanSansCN-Regular.woff') format('woff');
    font-weight: normal;
    font-style: normal;
}
body { font-family: 'CustomChineseFont', 'Microsoft YaHei', sans-serif; }
</style>
    

5. 解决方案层级三：自动化脚本集成与CI/CD适配

为避免重复部署问题，建议在项目根目录创建setup_chinese_font.py脚本：

import os
import shutil
import json

FONT_URL = "https://github.com/adobe-fonts/source-han-sans/raw/release/OTF/SimplifiedChinese/SourceHanSansSC-Regular.otf"
TARGET_DIR = "ComfyUI/web/fonts"

def ensure_chinese_font():
    if not os.path.exists(TARGET_DIR):
        os.makedirs(TARGET_DIR)
    
    font_path = os.path.join(TARGET_DIR, "SourceHanSansSC-Regular.otf")
    if not os.path.exists(font_path):
        print("Downloading Chinese font...")
        import urllib.request
        urllib.request.urlretrieve(FONT_URL, font_path)
    
    # 更新配置
    setting_file = "ComfyUI/settings.json"
    if os.path.exists(setting_file):
        with open(setting_file, 'r+', encoding='utf-8') as f:
            config = json.load(f)
            config['font_path'] = './fonts/SourceHanSansSC-Regular.otf'
            f.seek(0)
            json.dump(config, f, indent=2, ensure_ascii=False)
            f.truncate()

if __name__ == "__main__":
    ensure_chinese_font()
    

6. 系统架构视角：多平台兼容性设计

为实现跨平台一致性，应采用条件判断加载不同字体路径：

// 在 main.js 中动态注入样式
const isWin = navigator.platform.indexOf('Win') !== -1;
const chineseFont = isWin 
    ? 'Microsoft YaHei' 
    : 'PingFang SC, Hiragino Sans GB';

document.body.style.fontFamily = `'${chineseFont}', sans-serif`;
    

7. 可视化流程图：乱码问题处理路径

graph TD
            A[界面出现方框或问号] --> B{是否为Windows系统?}
            B -- 是 --> C[检查C:\\Windows\\Fonts是否存在微软雅黑]
            B -- 否 --> D[检查系统字体缓存]
            C --> E[确认ComfyUI是否引用本地字体]
            D --> E
            E --> F{前端是否加载中文字体?}
            F -- 否 --> G[部署WOFF字体并更新CSS]
            F -- 是 --> H[检查HTTP响应头Content-Type与编码]
            G --> I[重启服务验证]
            H --> I
            I --> J[问题解决]

8. 高级调优：性能与兼容性权衡

大型字体文件可能导致首屏加载延迟。可通过子集化（subset）生成仅包含常用汉字的轻量字体：

• 使用pyftsubset工具提取Unicode范围U+4E00~U+9FFF
• 压缩后字体体积可减少70%以上
• 结合font-display: swap提升用户体验

9. 监控与日志增强

在启动时加入字体检测逻辑，并输出诊断信息：

# 在 server.py 中添加
import fontTools.ttLib

def check_font_health():
    try:
        font = fontTools.ttLib.TTFont("web/fonts/SourceHanSansCN-Regular.woff")
        cmap = font.getBestCmap()
        if 0x4E00 in cmap:
            print("[INFO] 中文字体加载正常，包含基本汉字区")
        else:
            print("[WARN] 字体可能缺少中文字符映射")
    except Exception as e:
        print(f"[ERROR] 字体解析失败: {e}")