Extensions/Local Gallery
ComfyUI Extension

Local Gallery

Browse local image folders inside ComfyUI: waterfall grid, hover to read the matching prompt file, click to select, then output images and prompts one by one. Fully offline, bilingual UI.

By wanet36·Created a day ago·Updated a day ago· 0
wanet36/ComfyUI-LocalGallery
Nodes—
On cloudLocal install
Stars0
Updateda day ago
Readme

本地图库浏览器 · ComfyUI Local Gallery

在 ComfyUI 里直接浏览本机图片文件夹：瀑布流看缩略图、悬停读同名提示词、点选后由节点按列表逐张输出。 纯离线 —— 不联网、不需要账号、不往模型目录写缓存。

中文 ｜ English

<img src="docs/main.jpg" width="500" alt="图库主界面">

为什么用它

  • 不用先上传：路径指向本地文件夹（或单张图），刷出来就是瀑布流；几百张也不卡
  • 提示词就在旁边：同目录同名的 .txt / .caption / .json 自动配对，悬停即看，选图时不用来回翻文件
  • 选完即出图：选中的图片 + 对应提示词写进隐藏参数，执行时按顺序逐个输出，接 KSampler / SaveImage 直接跑批量
  • 配套齐全：打标（WD14 + TIPO）、批量转格式压缩、收藏、回收站，都在同一个节点里

安装

方式一：ComfyUI Manager（推荐）

  1. 打开 ComfyUI 菜单 → Manager → Custom Nodes Manager
  2. 搜索 local-gallery 或 Local Gallery
  3. 点 Install → 重启 ComfyUI

已发布到 Comfy Registry。新版本提交后要过一轮官方安全审核，刚发布的几分钟内可能还搜不到，稍等再试，或先用下面的方式安装。

方式二：git clone（之后 git pull 即可更新）

cd ComfyUI/custom_nodes
git clone https://github.com/wanet36/ComfyUI-LocalGallery.git

方式三：下载压缩包

  1. 打开 仓库首页 → 绿色 Code 按钮 → Download ZIP
  2. 解压，把整个 ComfyUI-LocalGallery 文件夹放进 ComfyUI/custom_nodes/（确保压缩包里多余的 -main 后缀目录名已改回）

装完之后

  1. 重启 ComfyUI
  2. 画布右键 → local gallery → 本地图库浏览器 (Local Gallery)

本节点自身不需要额外依赖，只用 ComfyUI 自带的 Pillow / numpy / torch。 唯一的可选依赖是「反推」：打标复用已装的 ComfyUI-WD14-Tagger（需 onnxruntime），扩写复用 z-tipo-extension（需 kgen + llama-cpp-python）。两个都没装时节点照常工作，只有反推页不可用。

界面导览

从上到下五块：

| 区域 | 内容 | |---|---| | 顶栏 | 五个页签 图库 / 收藏 N / 提示词 N / 反推 N / 转换 N + 「每行 N 张」滑块 | | 路径栏（只在图库页） | 浏览、设置、⟳ 刷新、删提示词、删除选中、回收站 | | 筛选行 | 含子目录、仅有提示词、搜索范围按钮、搜索框、命中 / 总数 | | 内容区 | 瀑布流缩略图（按原比例，不裁方），滚到底自动加载下一页（每页 80 张） | | 底栏 | 已选计数、状态提示、全选 / 反选 / 清空选择 / 复制提示词 |

加路径

节点里路径列表是唯一入口，点路径栏最左的 浏览：

  • 左侧点盘符 / 文件夹下钻，右侧勾选图片
  • ＋ 加入此文件夹 = 整个目录加进来；添加选中图片 = 只加勾选的那几张
  • 已加入的路径就在弹窗里那一行（已加入 N 个路径），点 ✕ 单独移除，右侧「清空路径」一键清空
  • 加完弹窗不会自动关，可以接着加下一个

路径可以是文件夹、单张图片，也可以混着加；同一个文件被多条路径带出来只算一次。

重启不丢：路径同时记在浏览器 localStorage 和节点目录的 .last_paths.json，优先级是 工作流里的路径 > 本地 > 服务端，补上时会提示「已接上上次的路径」。

看与选

<img src="docs/hover.jpg" width="500" alt="悬停显示提示词">
  • 点缩略图 = 选中 / 取消，Shift + 点击 = 连选
  • 悬停浮出提示词全文（标题行是 文件名 · 分辨率 · 体积），读不到会写「未找到同名提示词」
  • 悬停右上角出现操作组：☆ 收藏 / ⤢ 大图预览 / 🗑 删除
  • 右上角 TXT 角标：绿 = 有同名提示词文件，灰 — = 没有
  • 搜索框默认按文件名 / 相对路径过滤，空格分隔多个关键词（全部包含才命中）

五个页签

图库

默认页。筛选、搜索、选图、批量删除都在这里，也是唯一显示路径栏的页面。

搜索范围按钮点一下切一档（会记住）：

| 档位 | 行为 | |---|---| | 名称 | 纯前端过滤，不读文件，最快 | | 提示词 | 把当前列表的提示词读出来搜，多关键词「与」关系，不区分大小写 | | 全部 | 名称或提示词命中 |

收藏

跨目录汇总所有收藏，和当前路径列表无关。

  • 缩略图上的 ☆ 点亮即收藏，已收藏的封面右下角常驻小金星
  • 收藏存在节点目录 favorites.json，跨浏览器、跨会话都在
  • 预览、悬停、大图、删除的行为和图库页完全一致
  • 删除图片时自动取消收藏，收藏页不会留死链
  • 设置 →「收藏」里可以一键导出：把收藏的图片和提示词复制到指定文件夹（同名跳过，不覆盖）

提示词

<img src="docs/prompts.jpg" width="520" alt="提示词页">

只显示文本，不显示缩略图，适合批量改 / 复制：

  • 页内还有二级切换：提示词 N / 无匹配提示词 N（下一节）
  • 固定跟随「图库」页：图库页怎么筛选，这里就列什么；切到收藏页也不会变成收藏的图（页签数字同理）
  • 不用先选图，始终列出列表里带提示词的那些
  • 每条：序号 + 文件名 + 提示词全文，右上「复制」「删除」
  • 右侧「复制全部」按顺序导出，空行分隔，可直接喂给下一批
  • 滚到底自动加载（每页 60 条），提示词并发 6 个读取并缓存
  • 离开再回来会记住停在哪一档

无匹配提示词是第二档：把「有 .txt 但同目录没有同名图片」的条目单独列出来 —— 这些在网格里永远显示不出来。每条给文件名、目录、提示词正文，可单条复制或「复制全部」。这一档同样按图库的路径统计，在收藏页里也照常可用。

反推

选中几张图 → 点 反推 页签 → 逐张识别成提示词 → 可手改 → 一键写回同名 .txt。

整条链路相当于工作流 LoadImage → WD14Tagger → TIPO → SaveText，但不用排队出图。

| 输出 | 说明 | 速度（本机 CPU） | |---|---|---| | 仅标签 | WD14 原始标签，逗号分隔 | 0.4~2.2 秒/张 | | TIPO 扩写标签 | 补全 danbooru 标签，不生成英文描述 | +2~8 秒/张 | | TIPO 标签 + 描述 | 标签 + 一段英文自然语言 | +3~10 秒/张 |

  • 用哪个模型：打标直接扫 ComfyUI-WD14-Tagger/models 里的 .onnx + .csv；扩写复用 z-tipo-extension 的 gguf 列表
  • 缺依赖会降级：没有打标模型 → 页面提示不可用；没有 TIPO → 下拉禁用，只能出标签
  • 写回方式三选一：已有 .txt 就跳过（默认）/ 覆盖（备份 .bak） / 追加到末尾
  • 阈值默认 0.35 / 角色阈值 0.85，「下划线换空格」默认开（long_hair → long hair）
  • 前缀（如 @wanet）加在每条最前面，进 TIPO 之前不加，避免污染模型输入
  • 任务在后台跑，关掉面板不中断；同一时间只允许一个任务
  • 这个页面刻意不显示批量删除，避免把「清空反推结果」误当成「删图」

转换

<img src="docs/convert.jpg" width="520" alt="转换 / 压缩页">

批量转格式、压体积、缩放，不经过显存，直接读写磁盘。

| 参数 | 说明 | |---|---| | 范围 | 选中的 N 张 / 当前列表全部 | | 目标格式 | 保持原格式（只压缩）/ JPG / WEBP / PNG / BMP / TIFF / GIF | | 压缩方式 | 按质量 0–100 滑块；按体积 填目标 KB，自动二分找能塞进去的最高画质 | | 缩放 | 不缩放 / 按长边 / 按百分比，可加「尺寸对齐」（2/8/16/32/64 的倍数，训练集常用） | | 输出位置 | 同目录 · 新文件（a.png → a.webp、a.jpg → a_c.jpg）/ 指定文件夹 / 覆盖原文件 | | 连同名提示词 | 默认勾选，新文件旁补一份 .txt |

  • 原图默认不动，可以先跑一批看效果
  • 底部固定进度条 + 当前文件名 + 3 / 3，随时可取消；跑完给 成功 3 张 · 7.1 MB → 208 KB · 省 97% · 耗时 1.0s
  • 任务跑着可以切去别的页签，回来进度还在
  • 输出到指定文件夹时，跑完可以一键「把输出文件夹加入路径」
  • 「覆盖原文件」有红字警告；覆盖 + 换格式会删掉旧文件（回收站里找不回来）
  • 参数记在浏览器里，下次打开还是上次那套

大图预览

<img src="docs/viewer.jpg" width="580" alt="大图预览">

底部一条工具条：‹ 3 / 300 › 翻页 ｜ ★ 收藏 ｜ 🗑 删除 ｜ − 100% + 缩放 ｜ ⤢ 适应窗口。

  • 翻页：← → 键或点箭头，第一张 / 最后一张时对应箭头禁用
  • 收藏：快捷键 F，网格里那张的星标立刻同步
  • 删除：先进确认框，确认后图片 + 同名提示词一起进回收站；删完自动切下一张，删空自动关闭
  • 缩放：滚轮（以指针为中心）、双击、+ / - 键，范围 20%–800%，点中间的百分比回 100%
  • 平移：放大后拖动，超出舞台的部分裁掉，不会顶破窗口；换图自动复位
  • 关闭：Esc 或点黑色空白处

设置

<img src="docs/settings.jpg" width="500" alt="设置面板">

路径栏的 ⚙ 打开，四组：

| 分组 | 内容 | |---|---| | 外观 | 界面语言（中文 / English）、主题（跟随 ComfyUI / 浅色 / 深色）、显示附加说明 | | 收藏 | 导出目标文件夹 + 导出按钮 | | 运行参数 | 缩略图尺寸 / 质量、扫描上限、单图最大边、最近浏览、回收站目录、允许删除、空选兜底 | | 高级 | 允许访问的根目录（白名单），留空 = 不限制 |

运行参数改完点「保存运行参数」才写盘（直接写 config.json，立刻生效，不用重启）。非法值不写盘，按钮旁红字说明原因。

| 字段 | 范围 | 说明 | |---|---|---| | 缩略图尺寸 | 96–640 px | 网格缩略图长边，保存后立刻按新尺寸重排 | | 缩略图质量 | 40–95 | JPEG 质量 | | 扫描上限 | 100–500000 | 一次最多读多少文件，超出截断并在状态栏提示 | | 单图最大边 | 512–65536 px | 超过的图在节点执行时跳过（省显存），预览不受影响 | | 最近浏览 | 3–50 条 | 历史文件夹保留条数 | | 回收站目录 | 绝对路径 | 留空 = 节点目录下 .trash，下方显示当前实际生效路径 | | 允许删除 | 开 / 关 | 关掉后前端拦下所有删除入口，后端也会拒绝（只读模式） | | 空选兜底 | 开关 + 张数 + 含子目录 | 工作流里没勾图时自动取前 N 张 |

  • 显示附加说明关掉后，设置和转换页里每项下面的解释段落全部收起，只留控件；警告红字和转换结果摘要不受影响
  • 恢复默认值只填表单不保存
  • 关闭方式：右上角红色「关闭」或 Esc；点空白处不关（调参数时手滑不会关掉）

中英双语

设置 → 外观 → 界面语言，中文 / English 两个按钮，切换立刻生效，选择记在浏览器里。

覆盖整块界面：五个页签、路径栏、筛选与搜索、底栏、提示词页、反推页、转换页、大图预览工具条、悬停气泡、设置面板、浏览弹窗、回收站、删除确认框、状态栏提示与报错。带数字的句子按整句模板翻译（删除 3 个文件？ → Delete 3 files?），切语言时按当前数据重算。

数字、文件名、路径、模型名不翻译；查不到的文案回落成中文（不会空白）。

装了 ComfyUI-DD-Translation 之类会把界面翻成中文的插件也没关系：本节点给面板和浮层加了 .file-browser 标记，该插件会跳过这些子树，切到英文不会再被翻回去。

提示词匹配规则

只认同名提示词文件，完全不读图片里内嵌的工作流参数。

「同名」按以下顺序查找（大小写、全半角不敏感）：

  1. a.png → a.txt → a.caption → a.prompt → a.tags → a.md
  2. a.png → a.json（支持 kohya captions 数组、prompt / caption / text 字段）
  3. 目录级（kohya 风格）：1_hatsune miku/ 下的 1_hatsune miku.txt，自动去掉 数字_ 前缀

找到的内容原样输出，不裁剪、不去权重括号。

提示词数量对不上？

磁盘上 .txt 数量常常大于面板里显示的条数，按顺序排查：

1. 提示词没有对应图片（最常见）

扫描只认「同目录同名」配对。有 a.txt 却没有 a.png，这条提示词永远不会出现在网格里 —— 它没有可挂载的缩略图。

状态栏会直接写：已读到 300 张图，悬停看提示词 · 27 个提示词匹配不到图片，鼠标停在状态栏上能看到前 8 个文件名。想看全部：进 提示词 页 → 点 无匹配提示词 N 胶囊。

2. 列表是扫描那一刻的快照

边出图边看图时，新图不会自动出现，点 ⟳ 重新扫描。

3. 筛选或选中在起作用

搜索框有词、勾了「仅有提示词」，都会缩小范围。

4. 个别卡片显示「读取失败」

服务端一时繁忙 / 超时。失败不会写缓存，卡片上有「重试」，点一下即可。

配置 config.json

这些字段都能在设置面板里改，手改 json 同样有效。

{
  "allowed_roots": [],            // 留空=任意路径；填了就只能浏览这些根目录
  "thumb_size": 320,              // 网格缩略图长边
  "thumb_quality": 82,
  "max_scan_files": 20000,        // 单次扫描上限
  "max_image_side": 8192,         // 超过这个尺寸的图在节点执行时跳过
  "allow_delete": true,           // false = 只读模式
  "trash_dir": "",                // 回收站位置，留空 = 节点目录下 .trash
  "recent_limit": 12,             // 历史文件夹条数
  "auto_select_when_empty": {     // 没勾任何图时是否自动取前几张
    "enabled": false,
    "limit": 4,
    "recursive": false
  }
}

节点输出

| 输出 | 类型 | 说明 | |---|---|---| | images | IMAGE（列表） | 每张选中图片，[1,H,W,3] float32，0~1 | | prompts | STRING（列表） | 与图片一一对应的提示词（执行时按同名文件现读） | | filenames | STRING（列表） | 文件名，便于和 SaveImage 对账 |

OUTPUT_IS_LIST = (True, True, True)，和原 DanbooruGalleryNode 一致：下游节点会按列表逐条执行（接 KSampler 会为每张图各跑一次）。

为什么不用系统「选择文件夹」对话框：ComfyUI 便携版的 python_embeded 普遍没编译 tkinter，服务端弹不出对话框。内置浏览器只走 HTTP 接口，任何环境都能用。

HTTP 接口（前端使用，也可自己调）

| 方法 | 路径 | 说明 | |---|---|---| | GET | /local_gallery/list?path=&recursive=0&only_with_prompt=0 | 目录扫描，返回每张图的 width / height | | GET | /local_gallery/thumb?path=&size=320 | 缩略图（磁盘缓存） | | GET | /local_gallery/prompt?path= | 单图提示词；给侧车文件时按侧车规则读（sidecar: true） | | GET | /local_gallery/orphans?path=&recursive=0 | 无匹配提示词明细 | | GET | /local_gallery/raw?path= | 原图 | | GET | /local_gallery/browse?path= | 目录浏览（空 path 返回盘符列表） | | POST | /local_gallery/describe {"paths":[...]} | 批量描述图片路径 | | POST | /local_gallery/delete {"paths":[...]} | 移到回收站（图片 + 同名提示词） | | POST | /local_gallery/delete_prompts {"paths":[...]} | 只移走同名提示词，图片保留 | | POST | /local_gallery/search {"files":[...],"q":"a b"} | 按提示词搜当前列表 | | GET | /local_gallery/favorites | 收藏列表（按时间倒序） | | POST | /local_gallery/favorites {"paths":[...],"action":"add\|remove\|toggle"} | 切换收藏 | | POST | /local_gallery/favorites/export {"dest":"...","overwrite":false} | 导出收藏 | | GET / POST | /local_gallery/ui/settings | UI 设置（favorites_export_dir） | | GET / POST | /local_gallery/config | 读 / 写 config.json（白名单字段，非法值 400） | | GET | /local_gallery/convert/info | 转换面板的可选项 + 是否有任务在跑 | | POST | /local_gallery/convert/start {"paths":[...],"options":{...}} | 启动后台转换，返回 job | | GET | /local_gallery/convert/status?job=&since=0 | 进度 + 增量结果 | | POST | /local_gallery/convert/cancel {"job":"..."} | 停在下一张之前 | | GET | /local_gallery/trash | 回收站清单（按批次） | | GET | /local_gallery/trash/thumb?batch=&stored=&size= | 回收站缩略图 | | POST | /local_gallery/trash/restore {"items":[{"batch","id"}]} | 按原路径恢复 | | POST | /local_gallery/trash/purge {"batch":"..."} / {} | 永久删除某批 / 全部 | | GET | /local_gallery/caption/info | 反推配置（可用模型 / 默认阈值 / TIPO 是否可用） | | POST | /local_gallery/caption/start {"paths":[...],"options":{...}} | 启动反推（同时只允许一个） | | GET | /local_gallery/caption/status?job=&since=0 | 反推进度 + 增量结果 | | POST | /local_gallery/caption/cancel {"job":"..."} | 停止反推 | | POST | /local_gallery/caption/write {"items":[...],"mode":"skip\|overwrite\|append","ext":".txt"} | 写回侧车 | | GET / POST | /local_gallery/paths | 上次用过的路径列表（服务端记忆） | | GET | /local_gallery/info | 配置概览 |

convert/start 的 options：format（保持原格式/JPG/WEBP/PNG/BMP/TIFF/GIF）、mode（按质量/按体积）、quality、target_kb、allow_shrink、scale（不缩放/按长边/按百分比）、long_side、percent、align（不对齐/2/8/16/32/64）、output（同目录 · 新文件/指定文件夹/覆盖原文件）、out_dir、with_prompt。

目录结构

ComfyUI-LocalGallery/
├── __init__.py          # 节点注册
├── nodes.py             # 节点定义（输出 images / prompts / filenames）
├── gallery.py           # 扫描、缩略图、配置、回收站、收藏
├── routes.py            # HTTP 接口
├── captioner.py         # 反推（WD14 / TIPO）后台任务
├── convert.py           # 转换 / 压缩后台任务
├── prompt_reader.py     # 提示词匹配与读取
├── favorites.py         # 收藏持久化
├── js/local_gallery.js  # 整个前端（面板 / 弹窗 / 样式 / 中英词条）
├── config.json          # 运行参数（可在设置面板里改）
└── docs/                # README 截图

常见问题

Q：选了图但节点输出为空？ 节点只在执行时读路径和提示词。确认图片已选中（缩略图有环状描边 + 序号），并且文件还在原处（状态栏会标红失效路径）。

Q：删除的图去哪了？ custom_nodes/ComfyUI-LocalGallery/.trash/<时间戳>/…，按批次分组，可在回收站里恢复或永久清空。位置可在设置里改到别的盘。

Q：为什么提示词页里没有某些图？ 那一页只列有同名提示词文件的图。检查是不是 .txt 名字和图片差了几个字符。

Q：能不能不开 ComfyUI 单独用这个图库？ 不能，前端依赖 ComfyUI 的接口和节点容器。但可以手动调上表中的 HTTP 接口。

许可证

MIT © 2026 wanet36

致谢

节点结构参考了 ComfyUI-Danbooru-Gallery 的 DanbooruGalleryNode。本项目把数据源从远端 Danbooru 换成本地文件夹，提示词来源改成同目录同名文件，并重写了前端、格式转换与反推流程。