简介：Simple-Gallery 是一份面向 Android 开发者与开源爱好者的图片视频查看库资源，核心价值在于提供无广告、界面简洁的媒体浏览方案，可直接集成到个人项目或二次开发中。压缩包为 zip 格式，整体约 4.52MB，上游未提供文件总数与类型明细，从项目定位看应包含库源码、示例工程及配置说明等模块，便于快速接入与调试。该资源已有 246 人学习下载，适合希望研究多媒体文件扫描、相册分类与滑动缩放等交互实现的中级开发者参考。借助其开源特性，读者可查看并修改源代码，学习如何组织本地与 SD 卡媒体、处理 JPEG/PNG/GIF 及 MP4/MOV/AVI 等格式，并参考智能相册按日期或地理位置归档、元数据显示与视频播放控制等设计思路，为自建图库应用或参与社区贡献提供可复用的实践基础。
1. 本地图库的另一种解法：Simple-Gallery 为什么值得动手搭一遍
手机相册越滚越大，云盘限速、广告弹窗、会员墙轮番上阵，很多人最后发现：真正想看的照片和视频，其实一直躺在自己的硬盘里。Simple-Gallery 这个标题指向的，就是一类「无需广告即可观看照片和视频」的本地图库方案——把散落在文件夹里的媒体文件，用一个干净的网页界面重新组织起来，浏览、缩略图、播放全在本地完成，不依赖任何第三方服务。它适合两类人：一类是手里攒了几百 GB 家庭影像、想给自己搭个私人相册的普通用户；另一类是想拿它当练手项目、顺带学静态站点生成和前端懒加载的开发者。这一章先把「它到底解决什么问题」讲清楚，后面几章再一步步落到目录结构、缩略图生成、播放器配置和部署上。
这类方案的核心价值不在「功能多」，而在「没有中间商」。传统在线相册的痛点是：上传要等、看要会员、广告插在照片之间、原图被压缩。Simple-Gallery 走的是另一条路——媒体文件始终留在本地磁盘，程序只负责扫描目录、生成缩略图、输出一个可离线打开的浏览界面。你不需要把照片交给任何人，也不需要联网才能翻看十年前的旅行照。代价是它不会帮你做云端备份，也不会自动同步手机新拍的照片，这些得靠你自己用同步工具解决。想清楚这个取舍，再决定要不要往下做。
2. 目录结构与媒体扫描：让程序先认识你的照片
动手之前，最容易被忽略的一步是「把文件放整齐」。很多人直接把相机导出的文件夹原样丢进去，结果日期乱、命名乱、视频和照片混在一起，生成出来的图库自然也是一团糟。Simple-Gallery 这类工具通常依赖目录约定来推断相册分组，所以第一步不是写代码，而是设计一套自己能长期维护的目录结构。
2.1 一套能长期用的相册目录约定
我一般会按「年份/事件」两级来组织，事件目录名用「日期-地点-主题」的格式，避免中文空格和特殊符号，因为后面生成 URL 和缩略图文件名时，特殊字符是最常见的翻车点。下面是一个可以直接抄的目录骨架：
photos/ ├── 2023/ │ ├── 2023-05-01_park_picnic/ │ │ ├── IMG_0001.jpg │ │ ├── IMG_0002.jpg │ │ └── VID_0003.mp4 │ └── 2023-08-12_beach/ │ └── IMG_0100.jpg └── 2024/ └── 2024-02-20_snow/ └── IMG_0200.jpg这个结构的好处是：年份目录天然形成一级分类，事件目录形成二级分类，程序扫描时只要按字典序排列，时间线就是对的。事件目录名里的日期用YYYY-MM-DD格式，是为了排序稳定；用下划线而不是空格，是为了避免 shell 脚本和 URL 编码出问题。媒体文件保持相机原始命名即可，不需要重命名，因为重命名会破坏 EXIF 里的原始信息关联，而且批量重命名一旦出错很难回滚。
提示：如果你的照片来自多个手机品牌，文件名可能重复（比如两台手机都有 IMG_0001.jpg）。这种情况下建议在事件目录下再按设备分一层，或者用脚本加前缀，否则生成缩略图时会互相覆盖。
2.2 用脚本扫描目录并生成清单
目录整理好之后，下一步是让程序知道「有哪些文件、分别在哪、是什么类型」。最稳妥的做法是先跑一个扫描脚本，生成一份 JSON 清单，后续的缩略图生成和页面渲染都基于这份清单，而不是每次现场遍历目录。这样做的好处是：扫描和渲染解耦，出问题时能快速定位是清单错了还是渲染错了。
import os import json from pathlib import Path # 支持的媒体扩展名，按需增减 IMAGE_EXT = {".jpg", ".jpeg", ".png", ".webp", ".gif"} VIDEO_EXT = {".mp4", ".mov", ".webm", ".mkv"} def scan_gallery(root: str): root_path = Path(root) albums = [] # 只遍历两级：年份/事件 for year_dir in sorted(p for p in root_path.iterdir() if p.is_dir()): for event_dir in sorted(p for p in year_dir.iterdir() if p.is_dir()): items = [] for f in sorted(event_dir.iterdir()): if not f.is_file(): continue ext = f.suffix.lower() if ext in IMAGE_EXT: media_type = "image" elif ext in VIDEO_EXT: media_type = "video" else: continue # 跳过非媒体文件 items.append({ "name": f.name, "type": media_type, # 相对路径，方便后续拼 URL "path": str(f.relative_to(root_path)).replace(os.sep, "/"), "size": f.stat().st_size, }) if items: albums.append({ "year": year_dir.name, "event": event_dir.name, "cover": items[0]["path"], # 默认用第一张当封面 "items": items, }) return albums if __name__ == "__main__": data = scan_gallery("./photos") with open("gallery.json", "w", encoding="utf-8") as fp: json.dump(data, fp, ensure_ascii=False, indent=2) print(f"扫描完成，共 {len(data)} 个相册")这段脚本的逻辑很直白：先按年份、再按事件两层遍历，遇到媒体文件就记录名称、类型、相对路径和大小。几个关键参数需要说明：IMAGE_EXT和VIDEO_EXT决定哪些文件会被收录，如果你有 HEIC 格式的照片，需要额外加进去，但要注意浏览器原生不支持 HEIC，后面还得转码；cover默认取事件目录下排序第一的文件，如果第一张恰好是视频，封面就会变成视频首帧，观感不一定好，可以改成优先选图片；path用相对路径而不是绝对路径，是为了让清单可以随目录整体迁移，换台机器不用重新生成。
扫描完成后，gallery.json就是整个图库的「黑匣子」——后面所有环节都读它。如果最终页面缺图，第一件事就是打开这个 JSON 看对应条目在不在，能省掉大量瞎猜的时间。
3. 缩略图生成：决定图库打开速度的关键一步
图库能不能用得舒服，八成取决于缩略图。直接把几 MB 的原图塞进页面，手机打开就是白屏转圈；缩略图生成得好，几百张照片也能秒开。这一步的核心是「按需生成、控制尺寸、保留比例」，同时要处理好视频封面这个特殊角色。
3.1 用 Pillow 批量生成固定宽度的缩略图
图片缩略图我一般用 Pillow 来做，逻辑简单、依赖少。关键参数是目标宽度和压缩质量：宽度太大失去缩略意义，太小又看不清；质量太高文件大，太低有噪点。实测下来，宽度 480px、JPEG 质量 82 是一个比较平衡的取值，既能看清内容，单张通常也就几十 KB。
from PIL import Image, ImageOps from pathlib import Path THUMB_WIDTH = 480 THUMB_QUALITY = 82 THUMB_DIR = Path("./thumbs") def make_thumb(src: Path, dst: Path): dst.parent.mkdir(parents=True, exist_ok=True) with Image.open(src) as im: # 按 EXIF 方向自动旋转，避免手机竖拍照片横过来 im = ImageOps.exif_transpose(im) im = im.convert("RGB") # 统一色彩模式，避免 PNG 透明通道报错 w, h = im.size ratio = THUMB_WIDTH / w new_size = (THUMB_WIDTH, int(h * ratio)) im = im.resize(new_size, Image.LANCZOS) im.save(dst, "JPEG", quality=THUMB_QUALITY, optimize=True) def build_thumbs(albums): for album in albums: for item in album["items"]: if item["type"] != "image": continue src = Path("./photos") / item["path"] dst = THUMB_DIR / item["path"] dst = dst.with_suffix(".jpg") # 统一输出 jpg make_thumb(src, dst) item["thumb"] = str(dst).replace("\\", "/") if __name__ == "__main__": import json with open("gallery.json", encoding="utf-8") as fp: albums = json.load(fp) build_thumbs(albums) with open("gallery.json", "w", encoding="utf-8") as fp: json.dump(albums, fp, ensure_ascii=False, indent=2)这里有几个容易踩的点。ImageOps.exif_transpose必须调用，否则手机竖拍的照片在网页上会横过来，这是最常见的「玄学」问题之一；convert("RGB")是为了处理带透明通道的 PNG，直接存成 JPEG 会报错；Image.LANCZOS是重采样算法，比默认的 NEAREST 慢一点但边缘更干净，缩略图这种一次性任务值得用好的。生成完成后把thumb字段写回清单，渲染时直接读这个字段，不用再算路径。
3.2 视频封面：用 ffmpeg 抽第一帧
视频没有「缩略图」这个概念，得从视频里抽一帧当封面。ffmpeg 是最稳的工具，一条命令就能搞定。关键参数是抽帧时间点：抽第 0 秒经常遇到黑场或片头，抽第 1 秒通常能拿到比较有代表性的画面。
# 从视频第 1 秒抽一帧，缩放到 480 宽，输出 jpg ffmpeg -ss 1 -i "photos/2023/2023-05-01_park_picnic/VID_0003.mp4" \ -frames:v 1 -vf "scale=480:-1" -q:v 3 \ "thumbs/2023/2023-05-01_park_picnic/VID_0003.jpg" -y-ss 1表示从第 1 秒开始定位，放在-i前面比放在后面快很多，因为它是快速定位而不是解码到那一帧；-frames:v 1表示只取一帧；-vf "scale=480:-1"表示宽度缩到 480，高度按比例自动算；-q:v 3是 JPEG 质量，数值越小质量越高，3 左右观感就不错了。批量处理时用 shell 循环遍历清单里的视频条目即可，注意输出目录要先建好，否则 ffmpeg 会直接报错退出。
注意：如果视频是竖屏拍摄的，抽出来的帧也是竖的，缩略图网格里会出现高低不齐的情况。常见做法是在 CSS 里给缩略图容器固定高度并用
object-fit: cover裁切，这样视觉上整齐，代价是竖屏视频封面会被裁掉上下部分。
4. 前端浏览与播放：把清单渲染成能用的页面
清单和缩略图都齐了，最后一步是把它们变成人能看到、能点的界面。这一步不需要框架，原生 JavaScript 加一点 CSS 就够，好处是零构建、零依赖，双击 HTML 就能打开，也方便直接丢到任意静态托管上。
4.1 用原生 JS 渲染相册网格与灯箱
渲染逻辑分两层：外层是相册列表，内层是点开后的媒体网格。灯箱（点击放大）用最简单的遮罩层实现，视频用<video>标签直接播放，图片用<img>加载原图。
// 假设 gallery.json 和 index.html 同目录 async function init() { const res = await fetch("./gallery.json"); const albums = await res.json(); const app = document.getElementById("app"); albums.forEach((album) => { const section = document.createElement("section"); section.className = "album"; section.innerHTML = `<h2>${album.event}</h2>`; const grid = document.createElement("div"); grid.className = "grid"; album.items.forEach((item) => { const cell = document.createElement("div"); cell.className = "cell"; // 图片用缩略图，视频用抽帧封面 const cover = item.thumb || item.cover; cell.innerHTML = ` <img src="${cover}" loading="lazy" alt="${item.name}"> ${item.type === "video" ? '<span class="badge">视频</span>' : ""} `; cell.addEventListener("click", () => openLightbox(item)); grid.appendChild(cell); }); section.appendChild(grid); app.appendChild(section); }); } function openLightbox(item) { const mask = document.createElement("div"); mask.className = "mask"; const src = "./photos/" + item.path; mask.innerHTML = item.type === "video" ? `<video src="${src}" controls autoplay></video>` : `<img src="${src}" alt="${item.name}">`; mask.addEventListener("click", () => mask.remove()); document.body.appendChild(mask); } init();这段代码里有两个值得说的细节。loading="lazy"是浏览器原生的懒加载，滚动到可视区域才加载图片，几百张缩略图也不会一次性请求；灯箱里视频用controls autoplay，点开即播，点遮罩关闭。item.thumb || item.cover这个兜底是为了处理视频条目——视频没有thumb字段时用相册封面，但更合理的做法是前面 ffmpeg 抽帧后把结果写进thumb，这样每个视频都有自己的封面。
4.2 播放器与懒加载的几个必调参数
视频播放体验取决于几个参数，配错了要么卡要么费流量。下面这张表是我实际调过的取值，可以直接参考：
| 参数 | 建议值 | 说明 |
|---|---|---|
preload | metadata | 只预加载元数据，不下载整个视频，省流量 |
playsinline | 开启 | 移动端避免强制全屏播放 |
poster | 抽帧封面路径 | 播放前显示封面，避免黑屏 |
缩略图loading | lazy | 原生懒加载，减少首屏请求 |
| 原图加载时机 | 点击灯箱时 | 网格里只加载缩略图，原图按需加载 |
preload="metadata"是关键，默认的auto会在页面加载时就把视频文件拉下来，几个视频就能把带宽吃满；playsinline在移动端不加的话，点播放会跳全屏，体验割裂；poster配上抽帧封面，视频格子就不会是一片黑。这些参数单独看都很小，但组合起来决定了图库是「能用」还是「好用」。
5. 避坑与排查：这几处翻车我替你踩过了
做到这里，一个能跑的图库基本成型了。但实际用起来，问题往往出在细节上。下面这几条是我自己搭的时候真实遇到过的，按「现象 → 原因 → 解决」列出来，遇到类似情况可以直接对照。
现象一：页面打开一片空白，控制台报 CORS 错误。原因是用file://协议直接双击打开 HTML，浏览器出于安全策略不允许fetch本地 JSON。解决方法是起一个本地静态服务器，比如在目录下跑python -m http.server 8000，然后访问http://localhost:8000，问题立刻消失。这也是为什么我不建议把图库做成「双击即用」的单文件，本地服务器是更稳的选择。
现象二：缩略图生成了，但网页上显示的是裂图。原因通常是清单里的thumb路径和实际文件路径对不上，最常见的是 Windows 下反斜杠没替换成正斜杠，或者输出目录层级和原目录层级不一致。解决方法是打开gallery.json，随便挑一条thumb字段，手动拼出完整路径看文件在不在；如果不在，检查生成脚本里的dst拼接逻辑，确保THUMB_DIR和item["path"]的层级完全对应。
现象三：手机竖拍照片在网页上横过来了。原因是相机把方向信息写在 EXIF 里，浏览器渲染时不一定读。解决方法是在生成缩略图时调用ImageOps.exif_transpose，把方向「烧」进像素里，这样无论谁打开都是正的。这个坑几乎每个做图库的人都会踩一次，属于血泪经验。
现象四：视频封面全是黑的。原因是抽帧时间点选在了第 0 秒，很多视频开头就是黑场。解决方法是用-ss 1从第 1 秒抽，或者干脆抽第 3 秒；如果视频本身开头就是黑场，可以手动指定一个时间点。另外要确认 ffmpeg 命令里的输出目录已经存在，否则它会静默失败，你以为生成了其实没有。
现象五：相册多了之后，首屏加载越来越慢。原因是所有相册的缩略图都在首屏请求。解决方法是给相册列表做分页或折叠，默认只展开第一个相册，其余点击再渲染；或者用IntersectionObserver做更细粒度的懒加载。缩略图本身也要控制体积，480px 宽、质量 82 是经过验证的平衡点，再大就失去意义了。
6. 进阶技巧：让图库从「能看」变成「好用」
基础版本跑通之后，有几个小改动能明显提升日常使用体验，而且都不复杂，值得花半小时加上。
第一个是按时间线排序而不是按目录名排序。目录名排序依赖你命名规范，但如果你某天偷懒没按格式命名，顺序就乱了。更稳的做法是读 EXIF 里的拍摄时间，没有 EXIF 再回退到文件修改时间。Python 里用 Pillow 的_getexif()就能拿到，把时间写进清单，前端按时间排。这样即使目录名乱，时间线也是对的。
第二个是给缩略图加srcset做响应式。同一个缩略图，手机上看 480px 够了，桌面大屏上可能偏糊。可以生成 240px 和 480px 两档，用srcset让浏览器自己选。多一步生成，但省流量又清晰，性价比很高。
第三个是把清单生成和缩略图生成串成一条命令。手动跑两个脚本容易漏，写个Makefile或者一个build.sh，一条命令完成扫描、抽帧、缩略图、清单更新。我自己的习惯是每次导入新照片后只跑这一条命令，跑完直接刷新页面，不用记步骤。
第四个是给视频加时长显示。ffmpeg 的ffprobe能读出视频时长，写进清单，前端在视频格子角上显示「02:35」这样的标签。用户点之前就知道是长视频还是短视频，体验会好很多。命令是ffprobe -v error -show_entries format=duration -of csv=p=0 视频路径，解析输出即可。
最后一个习惯：每次改完生成脚本，先拿一个只有三五张照片的测试目录跑一遍，确认清单、缩略图、页面都正常，再对全量目录执行。全量跑一次可能几分钟，出错重来成本高；小目录验证只要几秒，能挡掉绝大多数低级错误。这个习惯帮我省下的时间，远比多写几行代码多。希望帮到你。
本文还有配套的精品资源，点击获取
