Tagger 是一个使用 Go 构建的本地音乐元数据管理工具。它把音乐文件当作事实源，在浏览器中读取和编辑 MP3、FLAC、WAV、Ogg Vorbis 和 Ogg Opus 的标签、歌词、封面和技术信息；需要补全时，再通过可插拔的数据源策略查询候选结果，并在逐字段审核后写回文件。
它不是音乐下载器，也不是面向公网的音乐流媒体服务。Tagger 的目标很简单：让个人音乐库的整理工作可解释、可恢复、可审计，并且在一台机器上用一个二进制文件启动。
为什么做 Tagger
音乐元数据整理通常同时面对三个问题：文件格式不统一、在线数据源不稳定、批量写入一旦出错就很难回退。Tagger 围绕这三个问题建立了几条明确的原则：
- 本地优先：音频文件留在你的音乐目录中，SQLite 只保存可重建的索引、任务和标签级历史。
- 先审核再写入：候选结果不是授权。标题、艺术家、专辑、歌词和封面都可以逐项选择，低置信度结果不会静默覆盖文件。
- 安全写入：写入前检查 revision，使用临时副本、写后重读校验和原子替换；每次成功修改都留下差异和历史。
- 策略隔离：MusicBrainz、LRCLIB、Apple/iTunes、网易云、酷我、酷狗和 LrcApi 都通过统一策略接口接入，单个来源失败不会阻断其他来源。
亮点一览
| 方向 |
Tagger 提供的能力 |
| 音乐文件 |
MP3、FLAC、WAV、Ogg Vorbis、Ogg Opus 的常用标签、原始 PropertyMap、时长、码率、采样率、位深、声道和嵌入封面 |
| 标签编辑 |
标题、艺术家、专辑、专辑艺术家、音轨/光盘号、年份、风格、歌词，以及注释、作曲家、指挥、作词家、版权、BPM、ISRC、MusicBrainz/AcoustID 标识 |
| 封面管理 |
读取、预览、上传、删除、远程候选预览；支持 JPEG/PNG/WebP 校验和 500×500 / 1000×1000 居中裁剪 |
| 数据补全 |
全部启用来源并行查询、跨源 Recording/Release 聚类、字段级智能选择、原始候选保留、歌词/封面独立采用和单曲重新匹配 |
| 批量任务 |
扫描、抓取、审核、写入和批量编辑使用 SQLite 持久化队列，支持进度、SSE 更新、取消、失败项重试和服务重启恢复 |
| 多曲库 |
启动时可以不提供音乐目录；设置页可添加、探测、切换多个本地曲库，目录以可折叠树状结构浏览 |
| 曲目浏览 |
服务端过滤/排序与游标分页，首屏默认 100 首，滚动追加；搜索、目录、递归、状态和格式条件不会把整座曲库加载到浏览器 |
| 页面恢复 |
同一 SPA 会话保留已加载页、筛选、跨页选择、当前曲目和滚动位置；整页刷新只恢复轻量筛选与滚动锚点，再按游标请求数据 |
| 批量安全 |
“全选”针对当前服务端结果集，批量补全/编辑/快照默认单次最多 2000 首；可在“设置 → 系统与安全”中调高，超限时提示先缩小范围 |
| 使用体验 |
跨页面全局播放器、浏览器路由、历史记录、主题/字体切换、无效封面默认留白、单用户可选访问令牌 |
| 部署 |
React 生产构建嵌入 Go 服务，运行时不需要 Node.js、FFmpeg 或系统 TagLib |
主要界面
- 曲库：左侧曲库和目录树，顶部搜索/格式/状态/递归过滤，中间曲目列表，右侧 Inspector 查看和编辑元数据。
- 分页浏览：曲目查询由 Go 服务端执行，首次只取约 100 首；继续滚动会用不透明游标追加下一页，底部显示已加载数量和匹配总数。离开曲库去任务、历史、设置或审核页再返回时，列表和滚动位置会恢复。
- 审核抓取结果：本地值与“智能选择 / 原始数据源”候选对比，逐字段显示真实来源，支持全选/取消、候选切换、歌词/封面详情预览、封面写入尺寸和连续审核。
- 任务中心：扫描、抓取、写入和批量编辑的持久化状态；显示处理进度、失败原因、取消和重试入口。
- 历史：按曲目查看字段 diff、标签快照和封面 blob，先预览再恢复，恢复本身也会产生新的审计记录。
- 设置：曲库注册与切换、数据源启用/配置/测试、主题字体、历史保留策略、封面占位和安全写入开关。
界面预览
因此，请把 Tagger 当作会修改文件的工具使用，并在首次批量操作前备份音乐目录。安全写入和历史恢复降低了风险，但不能替代文件系统备份。
快速开始
构建要求
- Go
1.25.7或更高版本
- Node.js
20+和 npm（仅构建前端时需要）
- 运行已构建的二进制不需要 Node.js、FFmpeg 或外部 TagLib
构建并启动
make build
./dist/tagger \
--music-dir /path/to/music \
--data-dir /path/to/tagger-data
Copy code to clipboard
默认监听127.0.0.1:8080，打开http://127.0.0.1:8080即可使用。生产构建必须使用make build，它会先编译 React，再把frontend/dist复制到web/dist，最后嵌入 Go 二进制。
如果不想在启动时指定音乐目录，也可以直接启动：
./dist/tagger --data-dir ./data
Copy code to clipboard
然后在设置页探测并添加音乐库。配置过的活动曲库会保存在 SQLite 中，后续启动时自动恢复；如果目录已经失效，Tagger 会保留旧索引并明确显示“未配置活动曲库”。
便携版
把 Tagger 的 Web 界面桌面程序利用AI打包成一个绿色免安装的 Portable便携版启动，不再单独使用浏览器打开，双击打开直接可用。
- 解压即用，双击
Tagger Portable.exe 启动，不写注册表、不安装到系统目录。
- 启动时不会出现命令提示符窗口。 程序以 GUI 子系统链接，Windows 不会为它分配控制台。
- 界面运行在程序内置的 WebView2 窗口中；缺少 WebView2 运行时时自动回退到默认浏览器。
- 所有运行数据（数据库、封面缓存、浏览器配置、日志）都保存在本文件夹的
data 目录中。
- 内置更新功能：先直连 GitHub，失败时依次使用
hk.gh-proxy.org、ghproxy.net 加速。
目录结构
Tagger Portable/
├── Tagger Portable.exe 主程序（含前端资源与图标）
├── 使用说明.md 本说明
└── data/ 运行时数据，首次启动自动创建
├── tagger.db SQLite 数据库（曲库索引、任务、标签历史）
├── artwork-cache/ 封面缓存
├── webview/ 内置窗口的浏览器配置
├── logs/ 运行日志
│ └── tagger.log 日志文件（超过 2 MB 自动轮转，保留一份 .1 备份）
└── tagger.lock 单实例锁
无控制台窗口
可执行文件通过链接器选项 -H windowsgui 链接，其 PE 子系统为
IMAGE_SUBSYSTEM_WINDOWS_GUI（2）而非控制台子系统（3）。这是双击启动时
不弹出命令提示符窗口的根本原因；scripts/build-portable.sh 会在打包前
校验该字段，回归时会直接让构建失败。
GUI 子系统没有附属的控制台，因此标准错误流在从资源管理器启动时不可用。
程序为此做了两处配套处理：
- 日志落盘：运行日志写入
data/logs/tagger.log。从终端启动时，日志同时
输出到终端与文件。
- 错误弹窗：导致程序退出的错误会弹出消息框（
#32770 窗口类），用户
无需查看日志即可得知失败原因。重复启动同一文件夹时不会报错，而是把焦点
交给已经运行的实例窗口。
有Bug去此反馈
便携版下载：
Tagger Portable 1.1.0 win-x64.zip https://drs.lanzouc.com/iH7ko4dqtbcb 密码:3yfz | 
[复制链接]
发表于 2026-10-28 16:16
