Redirect URI 三条红线不能踩

三条必须严格遵守的红线

红线一：不能用 localhost，必须用 127.0.0.1

Spotify 在 2025 年调整了对重定向 URI 的校验机制——原本可以接受的 http://localhost:766/callback 从某一天起开始拒绝。

正确写法：http://127.0.0.1:766/callback

错误写法：http://localhost:766/callback

为什么？因为 Spotify 的新校验逻辑把 localhost 视为一个可以解析到多个 IPv6 地址的动态域名，存在潜在的安全风险；而 127.0.0.1 是硬编码的 IPv4 回环地址，被视为安全的等效替代。

如果你在 2025 年 4 月 9 日之前就配置过自定义 API Client，必须现在就去 Spotify Developer Dashboard 里把旧的 localhost URI 删掉，改成 127.0.0.1。2026 年 3 月后旧 Client 将无法工作。

红线二：必须是 http，不能是 https

第二条红线：

✅ http://127.0.0.1:766/callback
❌ https://127.0.0.1:766/callback

为什么？因为 Lyricify 监听本地 766 端口用的是普通 HTTP，它没有也不应该自己签发 SSL 证书来处理本地 HTTPS 回调。Spotify 端注册什么 URI，Lyricify 端就用什么 URI 接收回调——如果 Spotify 把授权成功的回调发送到一个 https 地址，Lyricify 的 http 监听器是接不到的。

红线三：两条 URI 都要有

除了 http://127.0.0.1:766/callback，还要额外添加一条：

lyricify://callback

这是 Lyricify 的自定义深层链接协议。当授权在浏览器里完成后，Spotify 会按你注册的 Redirect URI 跳转——如果用的是 lyricify://callback，浏览器会直接唤起 Lyricify 客户端（不需要手动复制回调 URL），体验更好。

两条 URI 都添加的好处是：

浏览器自动唤起 Lyricify 时走 lyricify://callback
浏览器唤起失败、需要手动复制回调 URL 时走 http://127.0.0.1:766/callback

典型报错：INVALID_CLIENT: Invalid Redirect URI

看到这条报错，99% 是上面三条红线里踩了某一条。排查顺序：

打开 Spotify Developer Dashboard，找到你的应用 → Edit Settings
检查 Redirect URI 列表：

有没有 http://127.0.0.1:766/callback（http + 127.0.0.1）
有没有 lyricify://callback
有没有多余的 https://... 或 localhost 版本（应该删掉）

保存后退出 Lyricify，重新走一遍授权流程（用正确的 URI）

特别注意：Redirect URI 是精确匹配——大小写、末尾斜杠、协议头有一点不一样都会被判定为无效。