Nginx配置JSON响应与自定义内容详解

Linux如何配置Nginx返回JSON格式 Nginx自定义响应内容详解

若希望Nginx直接返回JSON数据，使用return指令配合default_type application/json是最直接的方法。但在实际操作中，遗漏任何关键配置项都可能导致浏览器直接下载文件、中文显示乱码或状态码不符合预期。这些问题通常并非Nginx的功能缺陷，而是响应头和语法细节未完全对齐所致。

在location中使用return返回JSON的基本方法

要使return指令正确返回JSON，必须同时满足三个条件：显式指定状态码、正确设置default_type、JSON字符串需用单引号包裹且不能包含换行。

• 状态码不可省略：例如必须写成return 200，仅写return是不行的。
• 必须声明Content-Type：default_type application/json这一行至关重要。缺少它，浏览器可能无法收到正确的Content-Type头，从而将响应视为二进制文件触发下载。
• 字符串使用单引号：JSON字符串必须用单引号（'{}'）包裹。因为在Nginx配置语境下，双引号容易被shell或配置解析器提前截断，引发语法错误。
• 保持字符串为单行：字符串内部不能有未转义的换行符，否则运行nginx -t检查配置时会报invalid number of arguments错误。

以下是一个标准示例：

location ~ ^/api/status$ {
    default_type application/json;
    return 200 '{"status":"ok","uptime":12345}';
}

中文JSON返回乱码的原因与解决方法

Nginx默认不会在响应头中声明字符集。虽然Linux系统普遍使用UTF-8编码，但部分浏览器（特别是旧版Chrome或IE）在未收到charset信息时，可能会自动回退到GBK等编码，导致中文显示为乱码或问号。

• 不要仅依赖default_type：default_type application/json仅设置了MIME类型，不包含编码信息。
• 必须显式声明UTF-8：最可靠的方法是使用add_header Content-Type 'application/json; charset=utf-8'。也可以使用更简洁的charset utf-8指令。
• 注意指令适用范围：需留意charset指令通常只对text/*类型的响应生效，对application/json可能无效。因此，优先推荐使用add_header来确保无误。

正确的配置应如下所示：

location ~ ^/api/hello$ {
    default_type application/json;
    add_header Content-Type 'application/json; charset=utf-8';
    return 200 '{"msg":"你好，世界"}';
}

为限流或错误场景返回自定义JSON（例如429）

当使用limit_req进行限流时，Nginx默认返回503状态码。然而，429（Too Many Requests）是更语义化、更符合RESTful规范的选择。Nginx本身不会自动为此状态码映射自定义响应体，需要手动配置。

• 第一步：定义限流区：在http块中配置限流规则，例如limit_req_zone $binary_remote_addr zone=api:10m rate=5r/s。
• 第二步：应用限流：在目标server或location中启用限流，如limit_req zone=api burst=10 nodelay。
• 第三步：错误页面重定向：使用error_page 429 = @rate_limited指令，将429错误定向到一个命名location进行处理。
• 第四步：构造JSON响应：在命名location中，必须同时使用return 429和add_header Content-Type来返回JSON。如果缺少add_header，返回的仍是默认的HTML错误页面。

配置片段示例如下：

server {
    error_page 429 = @rate_limited;

    location @rate_limited {
        add_header Content-Type 'application/json; charset=utf-8';
        return 429 '{"code":429,"message":"请求过于频繁，请稍后再试"}';
    }

    location /api/ {
        limit_req zone=api burst=10 nodelay;
        # ... 其他配置
    }
}

使用正则捕获URL参数动态构造JSON

有时需要根据URL路径动态返回JSON内容，例如访问/user/123即返回{"id":123}。这无需后端介入，利用Nginx自身的正则捕获和变量即可实现，但需注意类型和转义问题。

• 正则捕获变量：使用如location ~ ^/user/(\d+)$的规则可以捕获数字ID，并通过$1引用。注意，$1是字符串类型，但在JSON中数字值无需引号，因此拼接时应写成"id":$1。
• 不支持复杂表达式：return指令内部不支持表达式计算。像{"id":$1}这样的变量插值是合法的，但{"id":$1+1}会导致配置错误。
• 注意转义：如果JSON值中需要拼接中文或包含单引号，需确保整个JSON字符串仍被单引号包裹，且内部的单引号需转义为\'。
• 安全第一：尽量避免使用(.*)这类宽泛的匹配模式，恶意输入可能包含双引号或大括号，从而破坏JSON结构，导致前端解析失败。

一个相对安全的示例如下（仅匹配数字ID）：

location ~ ^/user/(\d+)$ {
    default_type application/json;
    add_header Content-Type 'application/json; charset=utf-8';
    return 200 '{"id":$1,"type":"user"}';
}

最后，有一个极易被忽略的陷阱：Nginx的return指令不会对JSON字符串的格式做任何校验。即使编写了格式错误的JSON，例如'{"key": "val}'（缺少右引号），Nginx也会照常返回，并且HTTP状态码依然是200。但这会导致前端的JSON.parse()解析失败。因此，在上线前，务必使用curl -v等工具实际请求，仔细验证响应头和响应体的内容是否完全符合预期。