如何解决 Spotify API 添加歌曲到队列时返回 404 错误的问题-js教程-PHP中文网

如何解决 Spotify API 添加歌曲到队列时返回 404 错误的问题

Spotify Web API 的 /me/player/queue 端点在设备未处于活跃播放状态时会返回 404 错误，即使 Track URI 有效、Token 正确且权限完备；根本原因在于该端点强制要求目标播放设备必须已启动并正在播放（或至少处于“活动”状态）。

spotify web api 的 `/me/player/queue` 端点在设备未处于活跃播放状态时会返回 404 错误，即使 track uri 有效、token 正确且权限完备；根本原因在于该端点**强制要求目标播放设备必须已启动并正在播放（或至少处于“活动”状态）**。

在使用 Spotify API 向当前播放队列添加歌曲时，开发者常遇到看似无解的 404 Not Found 错误——URI 格式正确（如 spotify:track:3OF9rTCYjLEplmYMynYvHG），访问令牌有效，其他 API（如获取用户信息、播放控制）均正常工作，但调用 POST /v1/me/player/queue?uri=... 却始终失败，并提示“Track not found in Spotify catalog”。这并非 URI 解析或权限问题，而是一个关键但文档未显式强调的行为约束：该端点仅在目标播放设备已激活且处于播放上下文时才可用。

? 根本原因解析

Spotify 的队列添加机制依赖于一个“活跃播放会话”。若用户未主动在某设备上启动播放（例如通过 PUT /v1/me/player/play 播放一首歌），或未显式指定 device_id，Spotify 将无法将请求路由至有效设备，进而返回 404（而非更明确的 400 或 403）。注意：此 404 不表示曲目不存在，而是“播放上下文不可用”。

✅ 正确调用流程（含代码示例）

必须确保以下三步按序执行：

确认或指定设备 ID（推荐显式传参，避免自动发现失败）
启动播放会话（哪怕仅播放 1ms 的静音曲目或占位曲）
再调用队列添加接口

// 示例：完整、健壮的队列添加逻辑
async function addTracksToQueue(trackUris, token, deviceId = null) {
  const baseUrl = 'https://api.spotify.com/v1';

  // Step 1: 获取可用设备列表（若未提供 deviceId）
  if (!deviceId) {
    const devicesRes = await fetch(`${baseUrl}/me/player/devices`, {
      headers: { Authorization: `Bearer ${token}` }
    });
    const devicesData = await devicesRes.json();
    const activeDevice = devicesData.devices.find(d => d.is_active);
    if (!activeDevice) {
      throw new Error('No active Spotify device found. Please start playback on a device first.');
    }
    deviceId = activeDevice.id;
  }

  // Step 2: 确保设备处于播放状态（使用一个最小化占位曲目）
  // 注意：此处使用一个公开、稳定、极短的免费曲目（如 Spotify 官方教程曲）
  const placeholderUri = 'spotify:track:2VZJl5QkKX6FfG78yPdVxL'; // 替换为实际可用曲目ID
  await fetch(`${baseUrl}/me/player/play?device_id=${deviceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      uris: [placeholderUri],
      position_ms: 0
    })
  });

  // Step 3: 添加目标曲目到队列（必须在播放启动后调用！）
  for (const uri of trackUris.slice(0, 10)) { // Spotify 限制单次最多 10 首
    const queueRes = await fetch(
      `${baseUrl}/me/player/queue?uri=${encodeURIComponent(uri)}&device_id=${deviceId}`,
      {
        method: 'POST',
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );

    if (queueRes.ok) {
      console.log(`✅ Added ${uri} to queue`);
    } else if (queueRes.status === 404) {
      console.warn(`⚠️  404: Queue endpoint unavailable — ensure device '${deviceId}' is playing.`);
    } else {
      console.error(`❌ Failed to add ${uri}: ${queueRes.status} ${queueRes.statusText}`);
    }
  }
}

// 调用示例
const myTrackUris = [
  'spotify:track:3OF9rTCYjLEplmYMynYvHG',
  'spotify:track:5Cf51sB6D1QhN7Q4q6cH2A'
];
addTracksToQueue(myTrackUris, 'your_access_token_here', 'your_device_id_optional');

⚠️ 关键注意事项

设备 ID 必须显式传递：即使只有一个设备，也建议在 queue 和 play 请求中都带上 device_id 参数，避免因设备自动选择失败导致 404。
播放必须真实触发：仅调用 play 接口不足以保证“活跃”，需确保 HTTP 响应为 204 No Content 且 Spotify 客户端实际开始播放（可监听 player_state_changed 事件验证）。
权限范围检查：确保 Token 具备 user-modify-playback-state 作用域（必需），且用户已在 Spotify 客户端登录并授权该设备。
错误处理不能仅依赖 status === 404：应结合响应体与业务逻辑判断——例如捕获 {"error":{"status":404,"message":"Player command failed: No active device found"}} 这类明确提示。
前端跨域与重定向风险：若在浏览器中直接调用，需确保 Spotify App 已配置正确的重定向 URI，且后端代理（如有）未意外修改请求头或 URL 编码。