Photo Walk

在线体验： https://byjming.github.io/PhotoWalk/ — 打开浏览器即可使用，无需安装任何工具。

Photo Walk 是一款在浏览器中运行的照片漫游编辑器。导入一次旅行、散步或城市记录的 照片，它会读取拍摄时间和 GPS，把照片整理成可播放的地图故事，并导出为可以独立发布 的网页。整个编辑过程在本地完成，无需账号，也不会把原始照片上传到 Photo Walk 服务。

主要功能

• 根据照片中的 EXIF GPS 和拍摄时间自动生成照片路线。
• 自动整理连拍和疑似截图，同时保留人工决定权。
• 从大量照片中生成故事精选，也可以逐张加入、移出或发布全部照片。
• 支持补充 GPX/GeoJSON 设备轨迹，以及为无 GPS 照片手工标记位置。
• 提供刊物、夜行、明信片三种发布风格。
• 可导出目录 ZIP 或单 HTML，并附带 Astro 和普通 HTML 的嵌入模板。

快速开始

需要 Node.js 22+、pnpm 11.1.2，以及当前版本的 Chrome 或 Edge。

Windows 一键启动

下载并解压项目后，双击 启动 Photo Walk.cmd。脚本会检查 本机环境和项目依赖：依赖已经就绪时会直接跳过安装；只有关键依赖缺失时才执行一次 pnpm install --frozen-lockfile。服务准备完成后会自动打开浏览器。

脚本不会自动安装 Node.js 或 pnpm，也不需要管理员权限。请保持启动窗口运行，关闭窗口 会同时停止 Photo Walk。

命令行启动

pnpm install --frozen-lockfile
pnpm dev

浏览器打开 http://127.0.0.1:4173。也可以先点击“演示项目” 熟悉界面，演示内容不会读取电脑中的照片。

如何制作一段照片漫游

1. 导入照片

点击右上角“导入照片”，一次选择同一天或同一次旅行的照片。Photo Walk 会读取拍摄时间、 GPS 和画面信息；带 GPS 的照片会立即出现在地图上，没有 GPS 的照片仍然可以参与选片。

2. 检查和整理照片

• 在“照片”中浏览、调整顺序、设置封面，或为照片手工补点。
• 在“检查”中确认模糊、曝光、连拍重复和疑似截图等提示。
• “不展示”会从成品中排除照片；“保留”会撤销排除。

检测结果只是帮助缩小检查范围，不会替你删除原始照片。

3. 选择路线和地图

照片自带的 GPS 已足够生成照片连线，GPX/GeoJSON 只是可选补充。如果相机时间与轨迹 存在偏差，可以在“轨迹”中调整相机时钟偏移。

默认使用 OpenStreetMap，无需配置。选择高德地图时，需要填写高德 Web JS API Key 和 securityJsCode，再点击“应用到地图”。配置会保存在当前浏览器，之后导入照片或刷新 页面不会自动切回 OpenStreetMap。

高德 Web Key 会出现在导出的静态网页中，不能当作服务端密钥。请使用独立的 Web Key， 设置精确的部署域名白名单、最低配额、用量告警，并保留轮换能力。

4. 调整故事精选

在“发布”中选择“故事精选”，Photo Walk 会按时间节奏挑选最多 24 张照片。点击“调整照片” 可以搜索并逐张加入或移出；从故事中移出的照片仍可保留为地图路线点。需要完整相册时， 切换为“全部已选”。

5. 设置成品样式

选择刊物、夜行或明信片主题，填写作品简介，并确认公开时间、时区、封面和需要排除的 位置区域。发布前的检查项会提示照片、路线、封面和地图是否已经准备好。

如果照片时间正好相差 8 小时，可先确认设备是否把 UTC 写入了不带时区的 EXIF；只有在 这种情况下才启用“无 offset 的 EXIF 按 UTC 解释”。

6. 导出和分享

• 目录 ZIP：推荐用于博客和网站，图片与代码分开，体积更合理。
• 单 HTML：适合直接发送或本地双击预览；内容过大时应改用目录 ZIP。

导出会把照片重新编码为 WebP，并根据发布数量自动调整尺寸和质量。24 张以内优先保留 1600 px 细节，照片较多时会逐档降低最长边，并以约 32 MiB 的图片总量为优化目标； 实际大小会随画面复杂度变化。

为了获得最佳画质，请在导入原图的同一浏览器会话中完成导出。刷新页面后项目仍会恢复， 但只有缓存预览的照片需要重新导入原图，才能重新生成高清发布图。

嵌入 Astro 或 HTML

目录 ZIP 自带 README.md 和可直接使用的嵌入模板。

Astro

1. 解压后将整个发布目录放到 Astro 项目的 public/photo-walk/。
2. 将 snippets/PhotoWalk.astro 放到 src/components/PhotoWalk.astro。
3. 在页面中导入并使用 <PhotoWalk />；需要时可传入 src、title 和 height。

普通 HTML

1. 将发布目录命名为 photo-walk，放在博客页面旁边。
2. 把 snippets/html.html 中的响应式 iframe 片段放到正文需要显示的位置。

目录版会通过 fetch 读取 walk.json，因此必须由 HTTP(S) 网站提供，不能直接用 file:// 打开。部署时请保留 assets/、thumbs/ 和 walk.json 的目录结构。

本地数据说明

• 原始照片只在当前页面会话中使用，不写入项目缓存。
• 浏览器缓存保存项目设置、分析结果和小尺寸预览，方便刷新后继续编辑。
• 导出的照片会重新编码为 WebP，不携带原始 EXIF。
• “清除全部缓存”会删除本浏览器中的项目、缩略图和高德配置，不会删除电脑中的原始文件。
• 照片 GPS 连线只连接实际拍摄点，不代表两次拍摄之间的真实行走路径；导入的设备轨迹会 单独标记为“设备 GPS 记录”。

参与贡献

欢迎提交 Issue 和 Pull Request。开发环境、测试要求和提交约定见 CONTRIBUTING.md，版本变化见 RELEASE_NOTES.md。

License

Photo Walk 自有代码使用 MIT License。第三方依赖与许可证见 THIRD_PARTY_NOTICES.md。