THE SETUP GUIDE

给你的音乐，
准备好下一站。

从申请 Spotify 应用到部署 Vercel，按顺序完成即可。
本项目使用 PKCE 授权，只需要 Client ID，无需 Client Secret。

开始前：确认使用范围
截至 2026 年 11 月，Spotify 开发模式要求应用拥有者保持有效的 Premium 订阅，每个应用最多供 5 位加入白名单的用户使用。个人自用可以从开发模式开始；把网站部署上线，不代表自动获得面向所有用户的 API 权限。查看官方规则。

01 / 创建 Spotify 应用

登录 Spotify Developer Dashboard ，使用自己的 Spotify 账户，选择 Create app。
App name 填 Mixport；App description 可填 Import my music lists into Spotify playlists.。Website 可以在 Vercel 部署后填入正式地址；本地开发阶段可先按后台要求填写本地地址。
选择 Web API。Redirect URI 先添加 http://127.0.0.1:3000/api/auth/callback。确认条款后保存。
在应用 Settings 中找到 Client ID，稍后填到环境变量。无需复制或公开 Client Secret。
在 Settings → Users Management（部分界面显示 Users and Access）中，添加实际使用者的 Spotify 姓名和账户邮箱。建议确认自己的测试账号也在名单内。

如果 Create app 按钮不可用，先确认 Premium 状态及后台提示，以 Spotify 实际开放情况为准。

需要 Node.js 22 或更新版本。在项目目录中执行：

npm ci
cp .env.example .env.local
openssl rand -hex 32

将生成的随机字符串填入 APP_SESSION_SECRET，再编辑 .env.local：

SPOTIFY_CLIENT_ID=你的ClientID
APP_SESSION_SECRET=刚刚生成的随机字符串
APP_URL=http://127.0.0.1:3000

npm run dev

打开 http://127.0.0.1:3000。本地必须使用 127.0.0.1；Spotify 不接受 localhost 作为回调地址。环境变量修改后重启服务。

将项目源码上传到自己的 GitHub 仓库，保留 package-lock.json；不要提交 .env.local、node_modules 或 .next。
打开 Vercel → Add New → Project，导入仓库。Framework Preset 选择 Next.js，Build Command 保持 npm run build，Output Directory 保持默认。
如果仓库根目录直接是本项目，Root Directory 选择根目录；如果包含外层目录，则选含 package.json 的目录。Node.js 选 22 或更新的受支持版本。
可以先不填 Spotify 配置，点击 Deploy 获取正式域名。此时页面和歌曲清单解析可用，授权导入会提示先配置。
在 Project Settings → Environment Variables 添加下表中的三个变量，应用到 Production。然后执行 Redeploy，确保新配置生效。
回到 Spotify 应用 Settings，将正式回调地址 https://你的项目.vercel.app/api/auth/callback 添加到 Redirect URIs 并保存。Website 填入相同正式域名。将占位域名替换为你的真实地址。

变量	Production 填写内容
`SPOTIFY_CLIENT_ID`	Spotify 应用的 Client ID
`APP_SESSION_SECRET`	至少 32 个字符的随机密钥；推荐用 openssl 生成。只在服务端保存。
`APP_URL`	`https://你的项目.vercel.app`，不含路径或尾部斜杠。

日常使用固定的 Production 域名。随机 Preview 地址与已登记回调地址不同，不应用它测试 OAuth。绑定自定义域名时，同时更新 APP_URL 与 Spotify Redirect URI，再重新部署。

也可以在项目目录中运行 npx vercel，按提示登录、创建项目；设置好环境变量后用 npx vercel --prod 发布。

每次最多 500 首。Spotify 每批写入最多 100 首。默认创建私密歌单，不修改原平台歌单。中途失败会保留已创建的歌单，并显示已确认数量；请检查实际内容后再处理剩余歌曲。

可以整段粘贴分享文案，系统会识别其中的官方 HTTPS 链接。只读取歌曲信息，不需要提供来源平台密码。

来源	读取方式与限制
QQ / 网易云	公开歌单分页读取；受限曲目可能缺失，页面会提示。
酷我音乐	公开歌单链接自动分页，支持 playlist_detail 路径与 pid 参数。
酷狗普通分享	支持 gcid 分享链接及短链，公开页面可能仅返回前 10 首预览。完整迁移请导出 TXT / CSV 或粘贴完整歌曲清单。
酷狗专题 / 概念版	概念版集合（global_specialid=collection_…）支持分页。专题歌单会尝试分页，若重复返回预览，则停止并提示未读完整。
汽水音乐	公开歌单及分享短链支持游标分页。抖音同步收藏仅读取汽水可识别歌曲，不包含所有抖音原声或视频；页面会说明数量差异。

当列表可能不完整时，页面会持续显示提醒，并要求勾选「我已核对，继续处理当前读取到的歌曲」后才能开始匹配。也可直接切换完整歌曲清单导入。每次上限仍为 500 首。

INVALID_CLIENT / Invalid redirect URI：Spotify 后台的 URI 必须和 APP_URL + /api/auth/callback 完全相同，检查 HTTPS、域名、路径和尾部斜杠。
可以登录但请求报 403：确认使用者已加入白名单、应用拥有者 Premium 有效，且授权了歌单权限。调整后断开并重新连接。
429：可能是短时限流，也可能是开发账户配额用完。遵循页面等待提示；无恢复时间时稍后再试。同一开发账户的多个 Client ID 共享配额。
来源歌单解析失败或条目不全：确认公开歌单与完整链接。平台未提供稳定的开放歌单 API，本项目读取公开元数据，并会提示不完整结果。可以随时切换歌曲清单。
找不到某首歌：Spotify 曲库和地区版权可能不同。尝试原文歌名、歌手或替代译名，并手动选择候选版本；系统不保证所有歌曲都能匹配。
登录后状态丢失：使用固定域名，确认 Cookie 未被禁用、APP_SESSION_SECRET 未更换。密钥轮换会使旧会话失效。

文档核对日期：2026-11-07。平台规则和后台界面以后可能调整。