加auth_basic需避开三类高频错误：一是location匹配顺序错导致不生效，须用^~或=精确匹配/phpmyadmin；二是PHP解析失效，需确保auth_basic与fastcgi_pass同块且SCRIPT_FILENAME路径正确；三是htpasswd权限或格式错误，须用绝对路径、644权限及标准用户名:哈希格式。
直接加 auth_basic 就行，但必须避开 php 解析失效、路径匹配错位、密码文件权限错误这三类高频翻车点。
location 匹配顺序错了，auth_basic 根本不生效
常见现象是访问 /phpmyadmin/ 时没弹登录框，直接进去了或报 403/404。本质是 Nginx 先匹配了更宽泛的 location / 或 location ~ \.php$，把请求提前截走，根本没走到你写的带 auth_basic 的块里。
- 用
^~ /phpmyadmin（前缀匹配且优先级高于正则）或= /phpmyadmin（精确匹配），避免被其他 location 吞掉 - 不要把
auth_basic放在location /里——那会要求整个网站都认证，不是只锁 phpMyAdmin - 如果用了
alias，确认它和auth_basic在同一个location块内；alias和root不能混用，否则SCRIPT_FILENAME构造失败
PHP 脚本被当成静态文件下载，而不是执行
典型表现：点击登录页后浏览器直接下载 index.php，或返回 “No input file specified”。这是 auth_basic 和 PHP-FPM 处理逻辑冲突导致的——Nginx 把带认证的请求误判为静态资源，跳过了 fastcgi_pass。
- 确保
auth_basic和fastcgi_pass在同一个location块里，且fastcgi_param SCRIPT_FILENAME明确指向物理路径，例如：fastcgi_param SCRIPT_FILENAME $request_filename;（配合alias）或fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;（配合root） - 不要在
auth_basic块外单独写一个location ~ \.php$——它会覆盖你带认证的块 - 检查
fastcgi_index index.php;是否存在，否则访问/phpmyadmin/会找不到入口文件
htpasswd 文件路径或格式不对，认证始终失败
现象是弹出登录框，但无论输什么用户名密码都提示 “401 Authorization Required”，Nginx 错误日志里出现 user "xxx" was not found in "/path/to/htpasswd"。
-
auth_basic_user_file必须是绝对路径，例如/usr/local/nginx/conf/htpasswd；相对路径（如htpasswd）会以 Nginx 配置目录为基准，容易找错 - 文件权限需对 Nginx worker 进程用户（如
www-data或nginx）可读：chmod 644 /usr/local/nginx/conf/htpasswd - 每行只能有一个用户，格式严格为
username:encrypted_password，不能有空格或注释；推荐用openssl passwd -crypt或htpasswd -b生成，别手写哈希
最易被忽略的是：当你用 alias 指向 phpMyAdmin 目录时，auth_basic 块里的 fastcgi_param SCRIPT_FILENAME 如果还按 $document_root$fastcgi_script_name 拼，路径必然错——因为 $document_root 是站点根目录，不是 alias 指向的实际路径。这时候必须改用 $request_filename，它由 Nginx 在内部重写后给出真实磁盘路径。
立即学习“PHP免费学习笔记（深入）”；
