目录结构#

1
├── oriImg/           # [核心] 原始素材目录
2
│   ├── h/            # 横屏图片素材（强转为 .jpg）
3
│   ├── v/            # 竖屏图片素材（强转为 .jpg）
4
│   └── gif/          # 自定义分类（自动保留 .gif 后缀）
5
├── public/           # 构建产物目录（存放生成的十六进制图片和元数据）
6
│   ├── h/、v/、gif/   # 映射后的图片集合
7
│   └── counts.json   # 自动生成的全站索引文件
8
├── functions/        # Cloudflare Pages Functions
9
│   └── pic.js        # 由脚本生成的服务端重定向接口
10
├── components/       # Next.js 组件
11
│   └── image-gallery.tsx # 核心画廊组件（映射表逻辑）
12
├── gen_img.py        # 构建大脑：处理图片命名、后缀识别及生成元数据
13
├── index.js          # Cloudflare Workers 入口
14
└── README.md

前端预览#

1. 素材准备#

在根目录 oriImg/ 下创建分类文件夹。

• API 专用：创建 h 和 v 目录，放入横/竖屏图片（这些图片在输出时会固定为 .jpg 以兼容所有 API 客户端）
• 自定义分类：创建如 gif、anime 等目录。脚本会自动取该目录第一张图片的后缀作为该分类的输出后缀

2. 本地测试#

如果您想在本地预览画廊效果，请执行：

1
# 使用 --no-copy 快速生成虚拟文件进行测试
2
python gen_img.py --no-copy --hash-length 2
3
npm run dev

3. Cloudflare Pages/Workers 生产构建#

在 Cloudflare Pages 仪表板配置如下：

• 框架预设：Next.js
• 构建命令：

1
python3 gen_img.py --hash-length 2 && npm run build

• 输出目录：out
• 环境变量：确保 Python 环境为 3.8+

如果使用 Cloudflare Workers，则需要配置根目录的 wrangler.jsonc：

1
{
2
  "name": "srp-img-worker",
3
  "main": "index.js",
4
  "compatibility_date": "2026-01-05",
5
  "compatibility_flags": ["nodejs_compat"],
6
  "assets": {
7
    "directory": "./out",
8
    "binding": "ASSETS"
9
  }
10
}

注意：请将 name 改为你要部署的Worker名称；将 compatibility_date 改为你的部署日期。

部署命令：npx wrangler deploy

方式 A：服务端 API (JS 重定向)#

由生成的 functions/pic.js / index.js 提供支持，适合在 Markdown 或其他网页中直接引用。

方式 B：前端可视化画廊#

访问部署后的根域名（如 https://your-domain.pages.dev）：

• 自动适配：顶部导航会自动切换 h、v 或 gif 模式
• 瀑布流展示：基于 Next.js 的高性能瀑布流加载
• 沉浸式预览：集成 Fancybox，支持放大、旋转、全屏及下载

方式 C：URL 重写 (无感随机)#

需在 Cloudflare 仪表板手动配置 Transform Rules：

请将下列表达式与 <your-domain> 换成你的域名

URL重写规则一：

1. 匹配表达式：

1
(http.host eq "<your-domain>" and starts_with(http.request.uri.path, "/h") and not ends_with(http.request.uri.path, ".jpg")) or (http.host eq "<your-domain>" and starts_with(http.request.uri.path, "/v") and not ends_with(http.request.uri.path, ".jpg"))

2. 路径重写至：

1
concat(http.request.uri.path, "/", substring(uuidv4(cf.random_seed), 0, 2), ".jpg")

URL重写规则二：

1. 匹配表达式：

1
(http.host eq "<your-domain>" and starts_with(http.request.uri.path, "/gif") and not ends_with(http.request.uri.path, ".gif"))

2. 路径重写至：

1
concat(http.request.uri.path, "/", substring(uuidv4(cf.random_seed), 0, 2), ".gif")

注意：如果你的构建命令中 --hash-length 值为 3，那么这里 cf.random_seed 的随机范围右边边界也要从 2 改为 3。

URL访问示例：https://your-domain.pages.dev/h

关于 gen_img.py#

脚本执行时会进行以下操作：

1. 哈希扩散：通过 --hash-length 指定随机空间。若设为 3，每个分类会生成 $16^3$ 个访问路径
2. 后缀策略：
   • 检查 oriImg 下每个子目录
   • 若目录名为 h 或 v，输出后缀强制遵循命令行参数（默认 .jpg）
   • 否则，自动探测该目录首张图片后缀
3. 元数据导出：生成 counts.json，记录每个分类的图片总数 (counts) 和对应后缀 (category_exts)

1. 文件体积限制#

• 5MB 阈值：构建脚本 gen_img.py 会在扫描阶段检查每个源文件
• 策略：任何单文件体积超过 5MB 的图片将被直接忽略。它们不会被拷贝，也不会参与哈希迭代
• 原因：防止超大 GIF 或高分辨率素材在迭代（如 $16^3 = 4096$ 倍）后瞬间撑爆磁盘空间

2. 容量计算公式#

在配置 --hash-length 时，请参考以下公式评估预期的磁盘占用：

$S_{total} = \sum_{c=1}^{n} (16^L \times \bar{S}_c)$

• $S_{total}$：构建后的总磁盘占用
• $L$：命令行指定的 hash-length（默认 3）
• $\bar{S}_c$：分类 $c$ 中所有合规图片 ($\le$ 5MB) 的平均体积
• $n$：分类文件夹的总数

示例计算：若 h 分类有 10 张图，平均每张 500KB，hash-length 为 3：占用空间 $= 16^3 \times 500\text{KB} = 4096 \times 0.5\text{MB} \approx 2\text{GB}$

3. 最佳实践建议#

推荐一个好用的批量压缩工具：Caesium Image Compressor

• 预先压缩：建议在放入 oriImg 之前，使用工具（如 TinyPNG 或 FFmpeg）将图片/GIF 压缩至 2MB 以内
• 动态调整：如果您的图片库非常大，请将 --hash-length 设为 2（生成 256 张/分类），以确保部署成功率
• 查看日志：在 Cloudflare 构建日志中，脚本会明确提示：[分类名] 忽略了 X 个超过 5.0MB 的文件