HTTP 405 Method Not Allowed — 方法不被允许

症状

本篇指南处理“HTTP 405 Method Not Allowed — 方法不被允许”。请从症状出发，按顺序执行诊断，在推进前确认每个假设；随后通过修复与验证步骤闭环。

可观察到的症状包括：

• API 对存在的路由返回 405 “Method Not Allowed”
• GET 可用而 POST 返回 405
• 代理或预检改变了服务端看到的方法

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

curl -i -X POST https://api.example.com/items

Allow 头列出路由实际支持的方法，揭示正确的方法。

步骤 2

grep -rn "app.get\|app.post\|router.put" src/routes

对比注册的方法与客户端调用即可发现不匹配。

常见诱因（按出现频率排序）：

• 路由注册的方法与客户端使用不同
• 客户端发送了处理器未实现的方法（如对 GET 路由发 POST）
• 尾斜杠或代理重写把请求映射到了不同路由

根因

服务端找到了路径匹配但方法不匹配的路由，于是返回 405 并在 Allow 头中告知允许的方法。路径存在，方法错误。

修复

使用路由声明的方法；若操作合法则注册所需方法，并确保代理与客户端保留预期方法（PATCH 对 PUT、POST 对 GET）。

注意：为消除错误而让 GET 路由接受 POST 会破坏缓存与幂等语义。

// Express: register the needed verb explicitly
router.get('/items', listItems);
router.post('/items', createItem);

// client: use the verb the route declares
await fetch('/items', { method: 'POST', body: JSON.stringify(payload) });

# inspect allowed methods
curl -i -X OPTIONS https://api.example.com/items

验证

用正确方法发送并确认 2xx；验证错误方法仍返回 405 且 Allow 头准确。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。