如何让Nginx认证成功时返回自定义HTTP状态码？

你的配置失效的核心原因是：$status变量在auth_basic执行的阶段还未被赋值。Nginx的指令执行有明确的阶段顺序，auth_basic属于access阶段，而$status是在响应生成阶段才会被设置为最终的状态码，所以你用if ($status != 200)的判断逻辑完全不生效，反而会因为$status为空，导致条件始终成立，最终无论认证成功与否都返回401。

下面是两种可行的实现方案：

方案一：使用内部跳转（Named Location） #

这是最简洁的方式，利用Nginx的内部跳转机制，在认证通过后跳转到专门返回204的location：

server {
    listen 80;
    server_name example.com;

    location / {
        auth_basic "TEST";
        auth_basic_user_file /etc/nginx/.htpasswd;
        # 认证通过后，内部跳转至返回204的命名location
        rewrite ^ @auth_success;
    }

    # 命名location，仅用于内部跳转
    location @auth_success {
        return 204;
    }

    location /auth/off {
        auth_basic off;
        return 200;
    }
}

原理说明： #

• 当auth_basic认证失败时，Nginx会直接返回401响应，不会执行后续的rewrite指令；
• 当认证成功时，执行rewrite ^ @auth_success触发内部跳转，进入@auth_success块返回204状态码。

方案二：利用error_page捕获认证失败场景 #

如果需要更灵活的控制，可以用error_page捕获认证失败的401，再对成功的请求返回自定义状态码：

server {
    listen 80;
    server_name example.com;

    location / {
        auth_basic "TEST";
        auth_basic_user_file /etc/nginx/.htpasswd;
        # 认证成功则返回204
        return 204;
        # 捕获认证失败的401，直接返回（避免被后续默认处理覆盖）
        error_page 401 =401 @auth_fail;
    }

    location @auth_fail {
        return 401;
    }

    location /auth/off {
        auth_basic off;
        return 200;
    }
}

原理说明： #

• 正常情况下，认证通过后会执行return 204返回目标状态码；
• 当认证失败时，Nginx会触发401错误，通过error_page 401 =401 @auth_fail直接返回401，确保不会被其他逻辑干扰。

两种方案都可以实现你的需求，方案一更简洁推荐优先使用。修改配置后记得执行nginx -s reload重载配置生效。

内容的提问来源于stack exchange，提问作者Teddy