Host on pipo's site

Location匹配

Mon, 15 Dec 2025 11:54:12 +0800

匹配类型

修饰符	含义	示例
`=`	精确匹配	`location = /api`
`^~`	前缀匹配，匹配到就停止	`location ^~ /static/`
`~`	正则匹配（区分大小写）	`location ~ \.php$`
`~*`	正则匹配（不区分大小写）	`location ~* .(jpg\|gif\|png)$
无	普通前缀匹配	`location /api/`

精确匹配

location = /api {
 #.....
}
只有访问是 example.com/api 时才匹配
example.com/api/ ❌
example.com/apis ❌

前缀匹配

location ^~ /api/ {
 #....
}
example.com/api/ ✅
example.com/apis ❌
example.com/api/123456 ✅

正则匹配

location ~*  \.(jpg|gif|png)$ { #\. 是转义 $表示结束

}
example.com/avatar.jpg ✅
exampl.com/logo.svg ❌
example.com/logo.pngDoSomeDangerAction ❌
example.com/thepath/logo.png ✅

优先级

高  ┌─────────────────────┐
    │  =   精确匹配       │
    ├─────────────────────┤
    │  ^~  前缀匹配停止   │
    ├─────────────────────┤
    │  ~   正则（顺序）   │
    │  ~*  正则（顺序）   │
    ├─────────────────────┤
    │  无  最长前缀匹配   │
低  └─────────────────────┘

拼接规则

root & index

root 表示文件路径地址的根目录， index 表示当发送的请求是目录时会去该目录下查找的文件;

index 指令定义了当用户请求一个目录（而不是一个具体文件）时，Nginx 应该默认返回哪个文件;

location / {
 root /var/www/home/;
 index index.html index.htm index.php
}

当进入的请求是 example.com/ 时会匹配到上述 location 匹配段 拆下来 / ，root + / = var/www/home/ 因为查找的是 dir 而非 file ，所以根据 index 从前往后查找对应文件 / + index [1] = /index.html 重新在 conf 里匹配。

因为 /index.html 符合 / 的规则，于是 root + /index.html, 此时访问的是具体的文件，检查是否存在然后返回。

alias

alias 常为改善 root 可能导致的 路径重复问题 而使用。

location /images/ {
	root /var/www/assets/pics/;
	
}

我们请求访问时如果是 example.com/images/img.png 到这里会被拆解拼接 为 /var/www/assets/pics/images/img.png

但我们实际只是 暴露给用户的地址是 images 我们的图片路径并不在这里，此时为了保证 API 的易读性和我们后端资源的有序我们可以使用 alias

location /images/ {
	alias /var/www/assets/pics/;
	
}

拼接结果就是 /var/www/assets/pics/img.png

巨坑

使用精准匹配导致无法托管正确页面

如果我们用精准匹配去设置根目录为欢迎页，会出错

location =/ {
 root /var/www/home/;
 index index.html index.htm index.php
}


1977/12/15 15:45:24 [debug] 332923#332923: *17 http request line: "GET / HTTP/1.1"
1977/12/15 15:45:24 [debug] 332923#332923: *17 http uri: "/"
1977/12/15 15:45:24 [debug] 332923#332923: *17 http args: ""
1977/12/15 15:45:24 [debug] 332923#332923: *17 http exten: ""
1977/12/15 15:45:24 [debug] 332923#332923: *17 http header: "Accept: */*"
1977/12/15 15:45:24 [debug] 332923#332923: *17 http header done
1977/12/15 15:45:24 [debug] 332923#332923: *17 test location: "/avatar/"
1977/12/15 15:45:24 [debug] 332923#332923: *17 test location: "/404.html"
1977/12/15 15:45:24 [debug] 332923#332923: *17 test location: "/"
1977/12/15 15:45:24 [debug] 332923#332923: *17 using configuration "=/"    #使用“=/精准匹配”
1977/12/15 15:45:24 [debug] 332923#332923: *17 open index "/var/www/home/index.html" #检查index.html是否存在
1977/12/15 15:45:24 [debug] 332923#332923: *17 internal redirect: "/index.html?" #内部重定向
1977/12/15 15:45:24 [debug] 332923#332923: *17 rewrite phase: 1
1977/12/15 15:45:24 [debug] 332923#332923: *17 test location: "/avatar/"
1977/12/15 15:45:24 [debug] 332923#332923: *17 test location: "/static/"
1977/12/15 15:45:24 [debug] 332923#332923: *17 test location: "/health" #找不到了因为 /index.html 不匹配 /
1977/12/15 15:45:24 [error] 332923#332923: *17 open() "/etc/nginx/html/index.html" failed (2: No such file or directory), client: 127.0.0.1, server: localhost, request: "GET / HTTP/1.1", host: "localhost:8070" 
1977/12/15 15:45:24 [debug] 332923#332923: *17 http finalize request: 404, "/index.html?" a:1, c:2
1977/12/15 15:45:24 [debug] 332923#332923: *17 http special response: 404, "/index.html?"
1977/12/15 15:45:24 [debug] 332923#332923: *17 internal redirect: "/404.html?"
1977/12/15 15:45:24 [debug] 332923#332923: *17 rewrite phase: 1
1977/12/15 15:45:24 [debug] 332923#332923: *17 test location: "/avatar/"
1977/12/15 15:45:24 [debug] 332923#332923: *17 test location: "/404.html"
1977/12/15 15:45:24 [debug] 332923#332923: *17 using configuration "=/404.html"

解决方案

使用 try_files

try_files 检查文件是否按指定顺序存在，并使用第一个用于请求处理的寻得文件; 处理过程在当前语境下执行。

Checks the existence of files in the specified order and uses the first found file for request processing;

这样就避免了内部重定向
```
location =/ {
 root /var/www/home/;
 try_files /index.html =404 
}
```
将 root 放在全局

admin/ 与 admin 同时跳转同一 index

location /admin {
	alias /var/www/admin/;
	index index.html;
	try_files $uri $uri/index.html =404;
}

Reference

title: "Nginx基础知识从小白到入门"
image: "https://raw.githubusercontent.com/wsgzao/storage-public/master/img/20191113180648.png"
description: "Nginx基础知识从小白到入门"
url: "https://wsgzao.github.io/post/nginx/"
favicon: ""
aspectRatio: "96.79245283018868"

title: "Nginx 快速教程"
image: "https://raw.githubusercontent.com/dunwu/images/master/cs/web/nginx/nginx.jpg"
description: "nginx-tutorial"
url: "https://dunwu.github.io/nginx-tutorial/#/nginx-quickstart"
favicon: ""
aspectRatio: "56.26959247648903"

title: "Nginx 从入门到实践（2023年版）Nginx 简介 Nginx 是什么 nginx (engine x) 是一个  - 掘金"
image: "https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/75209bc63f284481ae19c0c98d41187e~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?"
description: "Nginx 简介 Nginx 是什么 nginx (engine x) 是一个 HTTP 和反向代理服务器，一个邮件代理服务器，一个通用的 TCP/UDP 代理服务器，最初由 Igor Sysoev "
url: "https://juejin.cn/post/7223653286464667703#heading-20"
favicon: ""
aspectRatio: "96.18268575323789"

title: "try_files 文档"
image: "https://nginx.org/img/nginx_logo.svg"
description: ""
url: "https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files"
favicon: ""
aspectRatio: "28.666666666666668"

title: "index 文档"
image: "https://nginx.org/img/nginx_logo.svg"
description: ""
url: "https://nginx.org/en/docs/http/ngx_http_index_module.html#index"
favicon: ""
aspectRatio: "28.666666666666668"

Nginx快速入门

Sun, 14 Dec 2025 20:30:12 +0800

安装

导入源（Debian/Ubuntu）

# 安装必要的证书包
sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring
# 导入 NGINX 官方签名密钥
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
# 添加官方稳定版仓库
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list
# 设置官方源的优先级高于 Ubuntu 源
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" | sudo tee /etc/apt/preferences.d/99nginx

安装 Nginx 软件包

sudo apt update                        
sudo apt install nginx

启动与配置

sudo systemctl start nginx #启动 Nginx

基本命令

nginx -s stop #强行关闭 
nginx -s quit #优雅关闭
nginx -s reload #重载配置
nginx -t #检查语法问题

检查语法错误与查看配置所在位置

sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

查看配置

user  nginx; #用户
worker_processes  auto;

error_log  /var/log/nginx/error.log notice; #日志地址
pid        /run/nginx.pid; 


events {
    worker_connections  1024; #最大链接线程数
}


http {
    include       /etc/nginx/mime.types; 
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    include /etc/nginx/conf.d/*.conf;  #具体配置位置
}

server {
    listen       80;
    server_name  localhost;

    #access_log  /var/log/nginx/host.access.log  main;

#    location /index {
#        root   /usr/share/nginx/html;
#        index  index.html index.htm;
#    }
	location / { 
	root html; # 网站根目录 
	index index.html index.htm; # 默认首页文件 
	}
    #error_page  404              /404.html;

    # redirect server error pages to the static page /50x.html
    #


    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }

    # proxy the PHP scripts to Apache listening on 127.0.0.1:80
    #


    #location ~ \.php$ {
    #    proxy_pass   http://127.0.0.1;
    #}
    # pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
    #


    #location ~ \.php$ {
    #    root           html;
    #    fastcgi_pass   127.0.0.1:9000;
    #    fastcgi_index  index.php;
    #    fastcgi_param  SCRIPT_FILENAME  /scripts$fastcgi_script_name;
    #    include        fastcgi_params;
    #}

    # deny access to .htaccess files, if Apache's document root
    # concurs with nginx's one
    #


    #location ~ /\.ht {
    #    deny  all;
    #}
}

快速配置

目标访问 test: 8005 跳转到本地 index.html

修改上面配置为

 listen 8005;
 server_name test;

location / { 
	root /var/www/test;
	 index index.html;
}

sudo mkdir -p /var/www/test/
sudo touch /var/www/test/index.html 
sudo tree /var/www/test/
/var/www/test/
└── index.html

重载配置

> sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
> sudo nginx -s reload

测试链接

> curl -v http://test:8005/
* Could not resolve host: test
* Closing connection
curl: (6) Could not resolve host: test

会发现无法访问原因有二：

当访问 test 时无法解析到对应 ip
选择的位置缺少权限解决方案：

在 hosts 里添加 127.0.0.1 test
赋予 Nginx 执行权限或者转到 /var/www/ 目录下

反代短链接不跳转：上游依赖 Host 头

背景

Nginx 对外监听：www.shortlink.com

反向代理到上游短链服务：nurl.ink

server {
  listen 80;
  server_name www.shortlink.com;

  location / {
    proxy_pass https://nurl.ink;
  }
}

现象

访问 http://www.shortlink.com/xxxx 没有按预期 301/302 跳转（或返回不对/404/落到默认站点）

关键判断

后端识别短码通常看的是“请求里的 Host 头 + path”
通过反代访问时，转发给上游的请求里，Host 往往还是 www.shortlink.com 上游按 Host 做站点路由/短链域名匹配时，就可能“不认这个域名”，所以不跳转。

注意：Host 是请求头（request header），不是“返回的 Host 头”。响应里一般没有 Host。

根因

Nginx 转发到上游时，没有把 Host 改成上游想要的 nurl.ink（或没按上游规则传递）
如果上游是 HTTPS，还可能需要 SNI：没开 proxy_ssl_server_name 会导致 TLS 层选错站点/证书，行为异常。

修复方案

让上游收到正确的 Host（两种写法选一种）：

location / {
  proxy_pass https://nurl.ink;

  # 方案 A：写死上游域名
  proxy_set_header Host nurl.ink;

  # 方案 B：用变量（
  # proxy_set_header Host $proxy_host;

  # 保留原始信息
  proxy_set_header X-Forwarded-Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

  
  proxy_ssl_server_name on;
}

验证方法

直连上游看是否会跳转：

curl -I https://nurl.ink/xxxx

走反代看是否和直连一致：

curl -I http://www.shortlink.com/xxxx

如果要确认“Host 造成的差异”，用 curl 人工指定 Host 做对比：

curl -I -H 'Host: nurl.ink' http://127.0.0.1/xxxx
curl -I -H 'Host: www.shortlink.com' http://127.0.0.1/xxxx

Reference

title: "Beginner’s Guide"
image: "https://nginx.org/img/nginx_logo.svg"
description: ""
url: "https://nginx.org/en/docs/beginners_guide.html"
favicon: ""
aspectRatio: "28.666666666666668"

Host on pipo's site

Location匹配

匹配类型

优先级

拼接规则

root & index

alias

巨坑

使用精准匹配导致 无法托管正确页面

Reference

Nginx快速入门

安装

导入源（Debian/Ubuntu）

安装 Nginx 软件包

启动与配置

检查语法错误与查看配置所在位置

查看配置

快速配置

反代短链接不跳转：上游依赖 Host 头

背景

现象

关键判断

根因

修复方案

验证方法

Reference

使用精准匹配导致无法托管正确页面