Express.js部署树莓派后无法处理外部请求故障排查

AI 小北

2026-9-3

问题背景

搭建的集成React组件的Express.js服务包含一项核心逻辑：收到对应请求时，若Spotify当前无正在播放的歌曲，则调用Spotify API播放指定曲目。其中/play端点的原始实现代码如下：

app.post("/play", (req, res) => {
  try {
    // requesting to play uses query params
    id = req.query.id;
    currPlayingID = 0;

    // get the currently playing song from the SPotify API
    axios({
      url: "https://api.spotify.com/v1/me/player/currently-playing",
      method: "get",
      headers: {
        authorization: `Bearer ${access_token}`,
      },
    })
      // set the currently Playing ID or to zero if nothing is playing
      .then((response) => {
        if (response.data !== null) {
          currPlayingID = response.data.id;
        } else {
          currPlayingID = 0;
        }
      });

    // only play the song if its not currently playing
    if (id !== currPlayingID) {
      // making a axios request to the Spotify API to play the Song with the ID
      axios({
        url: "https://api.spotify.com/v1/me/player/play/",
        method: "put",
        headers: {
          authorization: `Bearer ${access_token}`,
        },
        data: {
          uris: [`spotify:track:${id}`],
        },
      });
      res.status(204);
    }
  } catch (error) {
    res
      .status(404)
      .json({ message: "Couldn't get Info from Spotify API", error: error });
  }
});

故障现象

上述代码在桌面PC本地启动时可正常运行，部署到RaspberryPI（树莓派）后，/play端点无法正常处理外部请求，所有配置位置已更新为正确IP地址。
已验证在树莓派的SSH终端内使用cURL请求该接口可正常响应，初步判断故障与服务拒绝localhost以外的外部请求有关。不同客户端发起请求时的报错表现如下：

React客户端访问接口报错：

Failed to load resource: net::ERR_CONNECTION_REFUSED

POSTMAN发起请求报错：

Mixed Content Error: The request has been blocked because it requested an insecure HTTP resource

Python脚本发起请求时，服务端控制台输出报错：

[UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "AxiosError: Request failed with status code 400".] {
  code: 'ERR_UNHANDLED_REJECTION'
}

根因说明

三类报错并非由同一根因导致，分别对应配置问题、安全策略拦截、代码逻辑缺陷三类独立问题：

外部连接被拒绝的核心原因：Express监听地址配置错误
Express服务启动时如果绑定的是127.0.0.1/localhost，只会接收本地回环地址的请求，所有来自外部设备的请求会被操作系统直接拒绝，这也是本地cURL访问正常、外部设备访问报ERR_CONNECTION_REFUSED的直接原因。
混合内容拦截原因：前后端协议不匹配
该报错是客户端安全策略导致：如果发起请求的前端页面是通过HTTPS协议加载的，浏览器/客户端默认会拦截页面发起的HTTP明文接口请求，和服务端是否正常运行无关。
服务端400与未捕获Promise报错原因：代码异步逻辑存在缺陷
该问题和部署环境无关，本地运行时只是未触发错误场景，代码本身存在四个明显问题：
- 第一个查询当前播放曲目的axios请求是异步执行，代码没有等待请求返回就直接执行了后续的曲目ID判断，判断时currPlayingID永远是初始值0，核心判断逻辑完全失效
- 两个axios请求均未添加错误捕获逻辑，只要Spotify API返回非2xx状态（比如token过期、无活跃播放设备、参数错误），就会抛出未捕获的Promise异常
- 变量id、currPlayingID未添加let/const声明，会泄露为全局变量，并发请求时会出现变量值互相覆盖的问题
- 接口存在响应分支遗漏：当请求ID和当前播放ID一致时，代码不会返回任何响应，请求会一直挂起直到超时；另外res.status(204)仅设置状态码，没有调用send结束响应。

修复步骤

按以下顺序逐一修复即可解决所有问题：

修改服务监听配置，允许外部访问
将Express服务的监听地址改为0.0.0.0，绑定所有网卡，同时检查树莓派系统防火墙（ufw/iptables）是否开放服务对应端口：

const PORT = 3000; // 替换为你实际使用的端口
// 错误写法：仅允许本地访问
// app.listen(PORT, 'localhost', () => {})
// 正确写法：允许局域网内所有设备访问
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Service running, LAN access address: http://<树莓派局域网IP>:${PORT}`);
});

如果开启了ufw防火墙，执行sudo ufw allow <端口号>放行对应端口即可。

解决混合内容拦截问题
二选一即可：给Express服务配置HTTPS证书，让接口和前端页面都走HTTPS协议；或者将前端页面的访问协议改为HTTP，和接口协议保持一致。调试阶段可临时关闭客户端的混合内容拦截，但生产环境不推荐该操作。

修复接口异步逻辑缺陷
重写/play端点逻辑，修正异步等待、错误捕获、变量作用域、响应处理的问题，参考实现如下：

app.post("/play", async (req, res) => {
  try {
    const trackId = req.query.id;
    if (!trackId) {
      return res.status(400).json({ message: "Missing required track id parameter" });
    }

    let currPlayingID = 0;
    // 等待查询当前播放状态的请求返回后再执行后续逻辑
    try {
      const currentPlayRes = await axios({
        url: "https://api.spotify.com/v1/me/player/currently-playing",
        method: "get",
        headers: {
          authorization: `Bearer ${access_token}`,
        },
      });
      // Spotify接口返回的当前播放曲目ID在data.item.id路径下，原代码取值路径有误
      if (currentPlayRes.data?.item?.id) {
        currPlayingID = currentPlayRes.data.item.id;
      }
    } catch (err) {
      console.log("Fetch current playing track failed, treat as no active playback:", err.message);
      currPlayingID = 0;
    }

    if (trackId !== currPlayingID) {
      // 捕获播放接口的报错
      await axios({
        url: "https://api.spotify.com/v1/me/player/play/",
        method: "put",
        headers: {
          authorization: `Bearer ${access_token}`,
        },
        data: {
          uris: [`spotify:track:${trackId}`],
        },
      });
    }
    // 所有逻辑分支统一返回204状态并结束响应
    return res.sendStatus(204);
  } catch (error) {
    console.log("Play endpoint runtime error:", error);
    return res.status(500).json({
      message: "Failed to communicate with Spotify API",
      error: error.message
    });
  }
});

额外注意：Spotify的播放接口要求调用时必须存在至少一个已授权的活跃播放设备（比如登录了同一账号、处于打开状态的Spotify手机/PC/音箱客户端），否则会直接返回400错误，调用前可先请求/v1/me/player/devices接口确认可用设备。

内容的提问来源于stack exchange，提问作者Justin Hangöbl