Nginx 是一个免费开源且稳定高效的 Web 服务器程序,拥有反向代理以及负载平衡的功能,经常作为最前端的服务器,也很常用来实现「转址」(URL redirection)功能。

Nginx 的 ngx_http_rewrite_module 模块

「ngx_http_rewrite_module」是 Nginx 预设激活的模块,可以用来将符合某个正则表达式的网址转成别的网址。另外,它也提供了一些如 if、break、return 等常用的流程控制命令。

若要使用 ngx_http_rewrite_module 模块来实现转址功能,我们可以在 server 区块或是其子区块内使用「ngx_http_rewrite_module」模块提供的 rewrite 命令。例如:

rewrite ^ /123;

以上命令,可以将所有的网址都转址到 /123,并且继续运行同一个区块后续的命令。也就是说,/123 也还是可以之后再使用「ngx_http_rewrite_module」模块所提供的命令转成其它地址。这边要注意的是,rewrite 命令的正则表达式不会去比对原始网址中的查找(Query)参数,也就是问号 ? 和其后面的字符串,而且这些查找参数预设会被附加到新地址的后面。如果不想保留它们,可以在新地址的结尾加上问号 ?。

rewrite 命令也可以加入第三个参数,来进行更细微的控制,第三个参数值可以是以下几种之一:

  • last:使这个 rewrite 命令的正则表达式成立且转址(内部)之后,不会再去运行同一个区块后续的命令,而是会直接以新的地址来去寻找符合的 location 区块再重新去处理它。
  • break:使这个 rewrite 命令的正则表达式成立且转址(内部)之后,不会再去运行同一个区块后续的命令。
  • redirect:使这个 rewrite 命令的正则表达式成立且转址之后,直接以 HTTP 的 302 状态(Moved Temporarily)来回应客户端,使其暂时地使用新网址再发送一次请求。
  • permanent:使这个 rewrite 命令的正则表达式成立且转址之后,直接以 HTTP 的 301 状态(Moved Permanently)来回应客户端,使其使用新网址再发送一次请求,并让客户端知道原本的网址已经被永久转移到新网址了。

如果 rewrite 命令的第三个参数不是 redirect 或是 permanent,则转移过去的地址最好只能是以斜线 / 开头的路径,也就是要在同一个 server 区块下处理的资源。反之,如果要在不同的 server 区块甚至是不同的服务器主机间进行转址的话,rewrite 命令的第三个参数就使用 redirect 或是 permanent 吧!

借由正则表达式的群组功能,我们可以将原先地址中的部份字符串,动态填入至新的地址中。例如:

rewrite ^/api/(.*)$ /api/v1/$1;

以上命令,可以将 /api/xxx 或是 /api/xxx/yyy 等地址,转成 /api/v1/xxx 或是 /api/v1/xxx/yyy。

另外,在新的地址中,也可以使用 $scheme 变量来取得原先网址中所使用的通信协定。例如:

rewrite ^/(.*)$ $scheme://new-domain.com/$1 redirect;

以上命令,可以将所有的网址转到新的网域(new-domain.com),并且保留原先网址的通信协定。当然,以这个例子来说,比较好的作法是,直接利用 $request_uri 变量来取得原先网址中不包括前段通信协定和服务器名称的内容,如此一来就可以省下使用正则表达式来处理的运算资源。如下:

rewrite ^ $scheme://new-domain.com$request_uri? redirect;

别忘了在使用 $request_uri 变量时,最好在其后加上问号 ?,才能避免网址的查找参数被重复添加。例如原本的网址是 http://127.0.0.1/api?a=10,如果没有在 $request_uri 变量之后加上问号 ?,转出来就会是 http://new-domain.com/api?a=10?a=10。

如果想进行更高级的控制,可以使用 if、break 和 return 命令。if 命令可以判断一个变量是否不是 0 或是空字符串,如果不是的话,就会去运行该 if 区块中的命令。break 可以略过同一个区块中后续要运行的命令。return 命令会直接发送 HTTP 回应,完成路由。return 命令的参数必须要有 HTTP 状态码或是要转址到的新网址,如果两者都有的话,HTTP 状态码为第一个参数,网址则为第二个参数。

例如以下命令,直接以 HTTP 的 403 状态(Forbidden)来回应客户端。

return 403;

例如以下命令,直接以 HTTP 的 302 状态(Moved Temporarily)来回应客户端,使其暂时地使用新网址再发送一次请求。

return 302 https://magiclen.org;

常用的转址设置

底下以不同的情境,来区分 Nginx 的设置档写法。

整个网域都转到一个固定的网址(302 转址)

server {
    ...
 
    server_name 网域名称;
 
    rewrite ^ 固定网址 redirect;
}

同网域下,HTTP 转 HTTPS(永远使用 https)

server {
    listen 80; 
    listen [::]:80;
 
    server_name 网域名称;
 
    rewrite ^ https://网域名称$request_uri? permanent;
}

旧网域换新网域(301 转址)

server {
    ...

    server_name 旧网域名称;

    rewrite ^ $scheme://新网域名称$request_uri? permanent;
}

同网域转移目录(301 转址)

server {
    ...

    server_name 网域名称;

    location ^~ /旧目录名称/ {
        rewrite ^/旧目录名称/(.*)$ /新目录名称/$1 permanent;
    }
}

此处 location 命令所使用的 ^~,表示要判断路径前缀是否吻合。

将 Web 应用程序挂入至现有网域的某个目录下

server {
    ...

    server_name 网域名称;
 
    location ^~ /目录名称/ {
        proxy_pass Web应用程序的通信协定(通常是http)://Web应用程序绑定的网络界面IP:Web应用程序绑定的连接端口[/要挂入的Web应用程序网址路径];
    }
}