NextJS API处理器报错：未发送响应致请求停滞

问题分析 #

你遇到的报错API resolved without sending a response for /api/getPuzzle?puzzleName=00-foo&lang=en, this may result in stalled requests.，核心原因：

• fs.readFile是异步回调式API，外层handler函数会在文件读取完成前就执行完毕，NextJS检测到未发送响应就抛出该错误
• 原代码的try/catch无法捕获fs.readFile回调内的错误，异步回调的错误不在当前同步代码执行栈中
• 直接用字符串拼接路径存在安全风险，还可能因系统路径分隔符差异出错

修复方案 #

方案1：用同步读取API fs.readFileSync #

适合文件读取耗时短的场景，代码更简洁：

import fs from 'fs';
import path from 'path';
import type { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const { puzzleName, lang } = req.query;
  // 处理参数类型，req.query返回值可能是数组
  const safePuzzleName = Array.isArray(puzzleName) ? puzzleName[0] : puzzleName;
  const safeLang = Array.isArray(lang) ? lang[0] : lang;

  if (!safePuzzleName || !safeLang) {
    return res.status(400).send({ success: false, message: '缺少必要参数' });
  }

  const libraryDirectory = path.join(process.cwd(), 'library');
  try {
    const filePath = path.join(libraryDirectory, 'prompts', safeLang, `${safePuzzleName}.${safeLang}`);
    const data = fs.readFileSync(filePath, 'utf-8');
    return res.status(200).send({ data });
  } catch (e) {
    console.error('读取文件出错>>', e);
    return res.status(500).send({ success: false });
  }
}

方案2：用Promise版异步API（推荐） #

适合大文件读取，避免阻塞事件循环，需将handler改为async函数：

import fs from 'fs/promises';
import path from 'path';
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { puzzleName, lang } = req.query;
  const safePuzzleName = Array.isArray(puzzleName) ? puzzleName[0] : puzzleName;
  const safeLang = Array.isArray(lang) ? lang[0] : lang;

  if (!safePuzzleName || !safeLang) {
    return res.status(400).send({ success: false, message: '缺少必要参数' });
  }

  const libraryDirectory = path.join(process.cwd(), 'library');
  try {
    const filePath = path.join(libraryDirectory, 'prompts', safeLang, `${safePuzzleName}.${safeLang}`);
    const data = await fs.readFile(filePath, 'utf-8');
    return res.status(200).send({ data });
  } catch (e) {
    console.error('读取文件出错>>', e);
    return res.status(500).send({ success: false });
  }
}

额外优化点 #

• 增加参数校验：判断puzzleName和lang是否存在，避免因参数缺失导致路径错误
• 用path.join拼接路径：自动适配不同系统路径分隔符，规避手动拼接的安全问题
• 处理req.query参数类型：NextJS中同一参数多次传递时，req.query返回数组，需转为字符串确保路径正确

内容的提问来源于stack exchange，提问作者reactor