在 nginx 中配置 scgi 模块传递参数，核心在于使用 scgi_pass 指令将请求转发给后端服务，并通过 include scgi_params; 加载默认的参数映射表。如果需要传递自定义参数，必须手动设置 scgi_param 指令，因为默认的 scgi_params 文件通常只包含标准的 cgi/scgi 环境变量（如 scgi, request_method 等），不包含 http 请求头或自定义字段。配置完成后，nginx 会将处理后的键值对以二进制协议发送给后端。
如何传递自定义的 HTTP Header 到 SCGI 后端？
要传递自定义的 HTTP Header（例如 X-Custom-Header）到 SCGI 后端，需要在 location 块中使用 scgi_param 指令显式定义映射关系。Nginx 不会自动将 HTTP 请求头转换为 SCGI 环境变量，除非你明确指定了它们之间的对应规则。通常，自定义头部会被映射为带有 HTTP_ 前缀的大写变量名，或者根据后端框架的要求进行特定命名。通过这种方式，你可以确保特定的客户端数据被正确传递给运行在 SCGI 协议下的应用程序。
server {
listen 80;
server_name example.com;
location /scgi_app {
# 将请求转发到本地 SCGI 服务
scgi_pass 127.0.0.1:9000;
# 加载默认的标准 SCGI 参数
include scgi_params;
# 显式传递自定义 HTTP Header 'X-User-ID' 到后端的 'X_USER_ID' 变量
scgi_param X_USER_ID $http_x_user_id;
# 传递另一个自定义 Header 'Authorization'
scgi_param AUTH_TOKEN $http_authorization;
}
}
上述配置中，当客户端发送带有 X-User-ID: 12345 的请求时，Nginx 会将其提取并赋值给内部变量 $http_x_user_id，然后通过 scgi_param 将其作为 X_USER_ID 环境变量传递给端口 9000 上的 SCGI 后端。后端应用可以通过读取 X_USER_ID 来获取该值。如果未设置 scgi_param，该头部信息将不会出现在后端的 SCGI 环境中。
如何处理 POST 请求体（Body）的数据传递？
对于 POST 请求，Nginx 默认不会自动将请求体（Body）内容作为标准 SCGI 参数传递，因为 SCGI 协议本身支持通过标准输入（stdin）传输实体主体，但 Nginx 的 scgi_params 默认文件中并未包含指向 Body 内容的参数映射。若后端依赖 SCGI 环境变量接收数据（某些旧式实现），需手动配置；但更常见的做法是依赖 SCGI 协议规范，即后端从 stdin 读取数据。然而，如果必须将 Body 内容作为参数传递（例如用于调试或特定框架要求），可以使用 scgi_param 结合 $request_body 变量。需要注意的是，$request_body 仅在 Nginx 已经读取并缓存了请求体后才可用，这通常需要配合 client_body_buffer_size 或使用 proxy_request_buffering off; 类似的机制（但在 SCGI 中直接控制较少见，通常由 Nginx 自动处理缓冲）。在实际操作中，大多数现代 SCGI 后端直接从 stdin 读取 POST 数据，因此无需额外配置参数即可获取 Body。
# 假设后端需要从环境变量中获取 Body 内容（不推荐，仅用于演示）
# 注意：这要求 Nginx 先缓冲请求体
location /scgi_app {
scgi_pass 127.0.0.1:9000;
include scgi_params;
# 将请求体内容传递给名为 REQUEST_BODY 的环境变量
scgi_param REQUEST_BODY $request_body;
}
# 更标准的做法：不配置任何 Body 相关参数
# 让 SCGI 后端直接从 stdin 读取 POST data
location /scgi_app_standard {
scgi_pass 127.0.0.1:9000;
include scgi_params;
# 不需要额外配置，SCGI 协议会自动处理 Body 传输
}
在第一个代码示例中，scgi_param REQUEST_BODY $request_body; 尝试将请求体内容放入一个名为 REQUEST_BODY 的环境变量中。这要求 Nginx 能够访问 $request_body，这意味着请求体已经被缓冲。如果请求体很大，可能会导致内存占用增加。在第二个示例中，我们遵循 SCGI 的标准行为，不手动传递 Body 参数，而是依赖 Nginx 和 SCGI 协议的底层机制，将 POST 数据流式或直接传输给后端的 stdin。这是处理文件上传或大数据 POST 请求的正确方式，避免了内存瓶颈和配置复杂性。
当 SCGI 后端返回非 200 状态码时，Nginx 的行为是什么？
当 SCGI 后端返回非 200 状态码（如 404、500 等）时，Nginx 默认会将该状态码原样返回给客户端，而不会将其视为错误并进行内部重定向或替换，除非配置了 error_page 指令。SCGI 模块的行为与 proxy_pass 类似，它主要充当协议转换器和反向代理的角色。如果后端返回 502 Bad Gateway（通常是因为连接失败或协议解析错误），Nginx 会根据全局或局部配置的 error_page 进行处理。但如果后端正常响应并返回 404 Not Found，Nginx 会直接将这个 404 响应头和正文发送给客户端。开发者可以通过检查 Nginx 的错误日志来确认后端是否成功响应以及返回的具体状态码。此外，如果希望将特定的后端错误状态码转换为 Nginx 的内部错误页面，可以使用 error_page 指令捕获这些状态码。
