nginx错误页面路由本质是通过error_page将指定状态码重定向至内部uri，再由带internal和精确匹配（=）的location拦截处理；需配合root/alias、map变量及作用域控制实现全局或业务级定制。

错误页面的专属路由，本质是让特定 HTTP 状态码（如 404、500）的响应，走一个独立、可控的 location 处理路径，而不是混在常规请求逻辑里。关键不是“匹配错误状态”，而是用 error_page 指令把错误响应**重定向到某个内部 URI**，再由对应 location 拦截并处理这个 URI。

用 error_page 触发专属 location

error_page 不是直接返回文件，而是把错误“转发”给一个内部 URI（以 / 开头，不对外暴露）。这个 URI 必须由 location 显式定义，并加上 internal 指令，表示只允许内部跳转，禁止用户直接访问。

• 在 server 块中写：error_page 404 /_err_404;
• 紧接着定义：location = /_err_404 { internal; root /usr/share/nginx/html; }
• 确保 /usr/share/nginx/html/_err_404 文件存在，或配合 index 指令指向具体 HTML

区分业务与系统级错误路由

不同场景需要不同处理方式。全局错误页可设在 http 块，而业务定制页应放在具体 server 或 location 内，避免污染其他站点。

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

• 全局兜底（所有 server 共享）：http { error_page 500 502 503 504 /50x.html; }
• 单个站点定制（如仅对 api.example.com 生效）：server { server_name api.example.com; error_page 404 /api-404.html; }
• API 接口返回 JSON 错误：error_page 400 = @json_400; location @json_400 { default_type application/json; return 400 '{"code":400,"msg":"Bad Request"}'; }

location 匹配要精准且带 internal

错误专用 location 必须用 = 精确匹配，防止被其他前缀规则意外捕获；必须加 internal，否则用户访问 /_err_404 就会绕过正常流程直接看到错误页，失去控制力。

• ✅ 正确：location = /_err_404 { internal; root /var/www/errors; }
• ❌ 错误：location /_err_404 { ... }（普通前缀匹配，可能被 location / 兜底覆盖）
• ❌ 错误：location = /_err_404 { root /var/www/errors; }（缺 internal，外部可直访）

结合 geoip 或设备类型做差异化错误页

如果需按国家或终端返回不同错误页，可在 location 中引用变量，但 root 路径不能含变量——改用 alias 或 map 预定义路径。

• 先定义变量映射：map $geoip_country_code $err_root { default "/usr/share/nginx/html"; CN "/usr/share/nginx/html/cn"; US "/usr/share/nginx/html/en"; }
• 再在 location 中使用：location = /_err_404 { internal; root $err_root; }
• 注意：root 后接变量需在 http 块顶层定义 map，且 Nginx 版本 ≥ 1.11.3