🛡️ 智绘_安全批次加载器

Native batch loaders have a failure mode that bites anyone automating a folder: they choke when the file count doesn't line up with the batch size you assumed, or when your index walks off the end. ZH_SafeBatchLoader ("🛡️ 智绘_安全批次加载器") is built for that specific pain. It loads one image from a folder by index and, when the index goes out of bounds, does something sane instead of crashing - black image, loop, or hold-last, your choice.

It's from ComfyUI-ZhiHui, a Chinese-language utility pack, and the source reads like a love letter to WAS Node Suite's safe loader - same seed-as-index idea, same "never let a batch die" philosophy, rebuilt in the pack's own style. It's a niche tool for a niche problem, but if you've ever had a long batch run die on frame 2,431 because the folder was one file short, you know exactly why it exists.

How it works

Point it at a folder with path and a glob pattern (default *), and it lists the matching images, filters to raster formats, and sorts them. Then index_seed - despite the name, it's the index, not a random seed - selects the frame, and mode decides how:

• single_image - index_seed is an absolute index.
• incremental_image - in this implementation it also treats index_seed as the absolute index (the source explicitly simplifies WAS's stateful stepping to keep behavior predictable).
• randomize - index_seed is used as a seed for a random pick.

The out-of-bounds behavior is the whole selling point, and it's a three-way dropdown:

• return_empty_black (default) - out of range means a 512×512 black image plus an error filename, so the graph keeps running but you can see something went wrong.
• loop_sequence - wraps the index with modulo, so a batch counter that runs 1→N forever just cycles the folder.
• hold_last - clamps to the final image and sits there.

The inputs and outputs that matter

• path - the folder (raw OS path).
• pattern - glob, e.g. *.png.
• index_seed, mode, out_of_bounds_behavior - the selection logic above.
• allow_RGBA - keep alpha channels as-is; off (default) flattens RGBA to RGB.
• filename_text_extension - off means the filename output drops the extension.

Outputs: image (a single IMAGE) and filename_text (STRING, the basename).

Install

cd ComfyUI/custom_nodes
git clone https://github.com/zhuyungen/ComfyUI-ZhiHui.git

Restart ComfyUI. Base deps only, no models. ComfyUI Manager search "ComfyUI-ZhiHui" also works.

Where people get burned

The black-image default is a double-edged sword. It keeps the graph alive, but it also feeds a legitimately black frame downstream - so in a save-everything workflow you'll get a folder full of black PNGs when you walk past the end, and it may take a while to notice. If you'd rather fail loudly, that's what the error filename string is for: check it before trusting the image. Also note the non-recursive scan - it reads one folder level only, no subfolders. And keep an eye on filename_text_extension: with it off (default), a folder containing a.png and a.jpg will report the same filename for both, which can silently break name-based logic.