Nginx 直接返回固定 JSON：return 指令与 default_type 配置

Soulock
2026年06月01日
- 技术

Nginx 可以通过 return 指令直接返回固定响应，无需经过后端服务，适合 mock 接口、健康检查、维护模式等场景。

基本写法

location /api/status {
    default_type application/json;
    return 200 '{"code":200,"msg":"ok","data":null}';
}

default_type application/json 设置响应的 Content-Type，不设置则默认为 text/plain
return 200 '...' 返回 HTTP 200 和固定响应体
响应体用单引号包裹，内部 JSON 用双引号

禁用缓存

接口类响应通常不应该被浏览器缓存：

location /api/health {
    default_type application/json;
    add_header Cache-Control "no-store, no-cache";
    return 200 '{"status":"healthy","timestamp":"dynamic"}';
}

返回不同 HTTP 状态码

# 404 错误响应
location /api/v1/ {
    default_type application/json;
    return 404 '{"code":404,"msg":"接口不存在"}';
}

# 维护模式 503
location / {
    default_type application/json;
    return 503 '{"code":503,"msg":"系统维护中，请稍后再试"}';
}

多行 JSON：用变量

return 本身不支持换行，多行 JSON 用变量存储：

location /api/config {
    default_type application/json;

    set $json_body '{"version":"1.0","debug":false,"features":{"pay":true,"upload":true}}';

    return 200 $json_body;
}

根据请求方法区分

location /api/mock {
    default_type application/json;
    add_header Access-Control-Allow-Origin *;

    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
        add_header Access-Control-Allow-Headers "Content-Type";
        return 204;
    }

    return 200 '{"code":200,"data":[]}';
}

与 echo 模块对比

Nginx 标准版不支持 echo 指令，return 是不需要额外模块的内置方案。OpenResty（含 ngx_http_echo_module）可以用：

location /api/test {
    default_type application/json;
    echo '{"msg":"hello"}';
}

标准 Nginx 统一使用 return 即可满足固定响应需求。

#Nginx