用 Node.js 扫描商品图目录：尺寸清单与逐文件错误报告

　　批量商品图交付前，可以先用 Node.js 扫描目录，得到文件名、字节数与 PNG 头部声明的尺寸，并让单个坏文件留下错误记录而不终止全部扫描。下面的示例只读文件，不改图、不上传，也不把尺寸符合要求当成商品事实已经通过审核。

　　设想 Picset 工作流已经产出一批图片，运营拿到的目录里有成品、截断下载和说明文本。人工打开文件之前，程序可以完成一次机械清点：哪些 PNG 能读到头部，哪些缺少基本结构，哪个文件应该进一步检查。图像产生在哪里并不影响这项清点，它是独立的交付步骤。

最小实现：读头部，逐文件报错

　　把代码保存成 inventory.mjs。Node.js 模块以 .mjs 形式运行，使用内置文件系统模块读取目录；调用示例放在末尾注释中，修改目录后取消注释，再执行 node inventory.mjs。这里限定一层目录中的普通 PNG 文件，忽略子目录和其他后缀，不递归跟随文件链接。[1]

import { readdir, readFile } from 'node:fs/promises';
import path from 'node:path';
export async function inventory(directory) {
  const rows = [];
  for (const entry of await readdir(directory, { withFileTypes: true })) {
    if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.png')) continue;
    try {
      const b = await readFile(path.join(directory, entry.name));
      const signature = Buffer.from([137,80,78,71,13,10,26,10]);
      if (b.length < 33 || !b.subarray(0,8).equals(signature) ||
          b.readUInt32BE(8) !== 13 || b.toString('ascii',12,16) !== 'IHDR') {
        throw new Error('invalid PNG header');
      }
      const width = b.readUInt32BE(16), height = b.readUInt32BE(20);
      if (!width || !height) throw new Error('zero dimension');
      rows.push({ file: entry.name, width, height, bytes: b.length });
    } catch (error) { rows.push({ file: entry.name, error: error.message }); }
  }
  return rows.sort((a,b) => a.file.localeCompare(b.file));
}
// console.log(await inventory('./images'));

　　PNG 头部解析读取签名、IHDR 类型和宽高字段。签名不符、头部过短、首块长度异常或尺寸为零时，该文件进入 error 行。这样同一批里一个错误不会让后面的文件消失。输出按文件名排序，便于两次清单对照；排序并不表示图片的发布顺序。

用正常文件和失败输入验证

　　本次验证使用 Pillow 创建的纯色 PNG，尺寸为宽240、高120，另保存只剩前12字节的截断副本，并放入一个文本文件。扫描输出保留正常图的声明尺寸，将截断副本标为 invalid PNG header，文本文件没有进入清单。验证运行于 Node.js v24.16.0，检查脚本与输入保存在本批次制作区。

　　这一步不能证明完整 PNG 可以成功解码：代码没有检查所有块的 CRC，也没有解压像素内容。一个头部正确而图像数据损坏的文件，仍可能得到尺寸结果。因此字段宜叫声明尺寸或头部尺寸，不要写已验证清晰度。后续可以增加结构检查和实际解码，把不同层次的结果分别记录。

　　读文件采用顺序执行，比较容易理解，目录较大时可能不满足业务需要。示例将整份文件读进内存，因此也不适合任意大文件或不受控上传；实际项目应限制文件大小，或者只读需要的字节范围。输出里的错误文本用于本地排查，对外接口不宜直接泄露完整服务器路径。

　　这份清单与商品验收表应通过文件名和 SKU 关联，但脚本没有猜测商品身份。建议从业务资料提供对应关系，再由审核者确认颜色、接口、标签与包装内容。Picset 的公开产品入口是图像制作方向的来源，[2] 本文代码不是其内置功能，也没有调用其生成接口。

　　接到发布流程时，先保留机械清点结果，再完成图像解码、商品事实与版位预览。每个阶段写清楚已经检查什么、没有检查什么，可以避免一行 width 和 height 被误用成万能合格标识。目录扫描节省的是重复找文件的动作，不是熟悉商品的人必须做的判断。