如何在Nginx服务器上为指定目录配置Basic Authentication身份验证

问题原因及解决方案 #

你遇到的是Nginx下分路径配置Basic Auth的常见坑，核心原因和对应修复方式如下：

1. 前缀匹配被更高优先级的正则匹配截胡（最常见） #

Nginx的location匹配规则中，不带修饰符的普通前缀匹配优先级低于正则匹配。如果你的配置中存在处理静态资源的正则匹配块（比如匹配后缀jpg|png|css|html的缓存规则块），那么/private路径下的静态资源请求会优先匹配到正则块，而正则块中没有继承你写在location /private中的认证配置，就会出现验证反复失败的问题。

修复方式

给需要保护的路径location加上^~修饰符，强制让该前缀匹配优先级高于所有正则匹配：

location ^~ /private {
    auth_basic "Restricted Area";
    auth_basic_user_file /etc/nginx/.htpasswd; # 务必用绝对路径
    # 保留原有该路径下的root/alias、索引、try_files等配置
}

修改后重载Nginx配置即可生效。

2. 相对路径的密码文件在子location中解析错误 #

如果你使用相对路径指定密码文件，当location /private块中使用alias指令指定资源目录时，Nginx会将相对路径的基准改为alias指向的目录，而非默认的Nginx配置目录，导致找不到密码文件，验证失效。而全站配置时location /一般使用root指令，相对路径基准为配置目录，所以可以正常运行。

修复方式

将auth_basic_user_file的路径改为绝对路径，比如你把密码文件放在/etc/nginx/目录下，就写完整路径：

auth_basic_user_file /etc/nginx/.htpasswd;

3. 子location块内缺少必要的资源处理配置 #

如果location /private块中仅写了认证相关指令，没有配置资源访问规则（比如缺失root/alias、try_files、索引配置），会导致验证通过后Nginx无法找到对应资源返回403/404，容易被误认为是验证失败。

修复方式

在认证配置外补充该路径的资源处理规则，示例：

location ^~ /private {
    auth_basic "Restricted Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
    root /var/www/your-site; # 和站点根目录保持一致，或用alias指定private目录的绝对路径
    index index.html index.htm;
}

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