Archive for 四月, 2013



Syntax: location [ = | ~ | ~* | ^~ ] uri { … }
location { } @ name { … }
Context: server
Reference: location

This directive allows different configurations depending on the URI. It can be configured using both literal strings and regular expressions. To use regular expressions, you must use a prefix:

  1. “~” for case sensitive matching
  2. “~*” for case insensitive matching  大小写不敏感的匹配。
  3. there is no syntax for NOT matching a regular expression. Instead, match the target regular expression and assign an empty block, then use location /to match anything else.   匹配任意格式的URL。

The order in which location directives are checked is as follows: (注意:nginx的location配置 与顺序无关,采用如下的优先级

  1. Directives with the “=” prefix that match the query exactly (literal string). If found, searching stops.
  2. All remaining directives with conventional strings. If this match used the “^~” prefix, searching stops.
  3. Regular expressions, in the order they are defined in the configuration file.
  4. If #3 yielded a match, that result is used. Otherwise, the match from #2 is used.

Details below.

To determine which location directive matches a particular query, the literal strings are checked first. Literal strings match the beginning portion of the query – the most specific match will be used. Afterwards, regular expressions are checked in the order defined in the configuration file. The first regular expression to match the query will stop the search. If no regular expression matches are found, the result from the literal string search is used.

For case-insensitive operating systems, like Mac OS X or Windows with Cygwin, literal string matching is done in a case insensitive way (0.7.7). However, comparison is limited to single-byte locale’s only.

Regular expression may contain captures (0.7.40), which can then be used in other directives.

It is possible to disable regular expression checks after literal string matching by using “^~” prefix. If the most specific match literal location has this prefix: regular expressions aren’t checked.

The “=” prefix forces an exact (literal) match between the request URI and the location parameter. When matched, the search stops immediately. A useful application is that if the request “/” occurs frequently, it’s better to use “location = /”, as that will speed up the processing of this request a bit, since the search will stop after the first comparison.

It is important to know that nginx does the comparison against decoded URIs. For example, if you wish to match “/images/%20/test”, then you must use “/images/ /test” to determine the location.


location  = / {
  # matches the query / only.
  [ configuration A ]
location  / {
  # matches any query, since all queries begin with /, but regular
  # expressions and any longer conventional blocks will be
  # matched first.
  [ configuration B ]
location /documents/ { 以/document/开头的请求,先进行正则匹配,若找不到,则命中这儿(可比对下面理解)
  # matches any query beginning with /documents/ and continues searching,
  # so regular expressions will be checked. This will be matched only if
  # regular expressions don't find a match.
  [ configuration C ]
location ^~ /images/ { 所有以/images/开头的请求都命中这儿(可比对上面理解)
  # matches any query beginning with /images/ and halts searching,
  # so regular expressions will not be checked.
  [ configuration D ]
location ~* \.(gif|jpg|jpeg)$ { 大小写不敏感的匹配
  # matches any request ending in gif, jpg, or jpeg. However, all
  # requests to the /images/ directory will be handled by
  # Configuration D.
  [ configuration E ]

Example requests:

  • / -> configuration A
  • /index.html -> configuration B
  • /documents/document.html -> configuration C
  • /images/1.gif -> configuration D
  • /documents/1.jpg -> configuration E

Note that you could define these 5 configurations in any order and the results would remain the same.

The prefix “@” specifies a named location. Such locations are not used during normal processing of requests, they are intended only to process internally redirected requests (see error_pagetry_files).  内部location,不可以被url直接访问。


Syntax: alias path
Context: location
Reference: alias


This directive assigns a path to be used as the basis for serving requests for the indicated location. Note that it may look similar to the root directive at first sight, but the document root doesn’t change, just the file system path used for the request. The location part of the request is dropped in the request Nginx issues. Let’s see this in action. Consider the following example.

location  /i/ {
  alias  /spool/w3/images/;

A request for “/i/top.gif” will instruct Nginx to serve the file “/spool/w3/images/top.gif”. As you can see, only the part of the URI after the location is appended. The location itself, in this case “/i/”, is dropped. With a root directive the full path is appended, i.e., in the above example it would have been, “/spool/w3/images/i/top.gif” — hence including also the location “/i/”.

Aliases can also be used in a location specified by a regex.

For example:

location ~ ^/download/(.*)$ {
  alias /home/website/files/$1;

The request “/download/book.pdf” will return the file “/home/website/files/book.pdf”. Note again that only part of the request URI after the location is appended to the path defined by alias.

It is possible to use variables in the replacement path.

Note that there is a longstanding bug that alias and try_files don’t work together.



Syntax: try_files file … uri
try_files file … = code
Context: server
Reference: try_files

Checks for the existence of files in order, and returns the first file that is found. A trailing slash indicates a directory – $uri /. In the event that no file is found, an internal redirect to the last parameter is invoked. Do note that only the last parameter causes an internal redirect, former ones just sets the internal URI pointer. The last parameter is the fallback URI and *must* exist, or else an internal error will be raised. Named locations can be used. Unlike with rewrite, $args are not automatically preserved if the fallback is not a named location. If you need args preserved, you must do so explicitly:

try_files $uri $uri/ /index.php?q=$uri&$args;

Example use in proxying Mongrel:

try_files /system/maintenance.html $uri $uri/index.html $uri.html @mongrel;

location @mongrel {
  proxy_pass http://mongrel;

Note that you can specify an HTTP status code as the last argument to try_file since Nginx version 0.7.51. Here’s an example:

location / {
  try_files $uri $uri/ /error.php?c=404 =404;

When all other attempts to serve the content corresponding to the request fail issue a 404 Not Found.
Example of use with Drupal / FastCGI:

# for Drupal 6 or 7:
try_files $uri $uri/ /index.php?q=$uri&$args;

# a better version for Drupal 7 since it doesn't need q=$uri:
try_files $uri $uri/ /index.php?$args;

location ~ \.php$ {
  fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name; # if not already defined in the fastcgi_params file
  # any other specific fastcgi_params

In this example, the directive try_files

try_files $uri $uri/ /index.php?q=$uri&$args;

Is basically the same as this:

location / {
  error_page     404 = @drupal;
  log_not_found  off;

location @drupal {
  rewrite ^ /index.php?q=$uri last; # for drupal 6

Or this:

# DO NOT DO THIS! This is a terrible use of if.
if (!-e $request_filename) {
   rewrite ^ /index.php?q=$uri last;

try_files is basically a replacement for the typical mod_rewrite style file/directory existence check. It is supposed to be more efficient than using if – see IfIsEvil

Examples of use with WordPress and Joomla (typical “Front controller pattern” packages)

# wordpress (without WP Super Cache) - example 1
try_files $uri $uri/ /index.php?q=$uri&$args;

# wordpress (without WP Super Cache) - example 2
# It doesn't REALLY need the "q" parameter, but without an explicit $args php
# gets an empty QUERY_STRING, breaking generated responses that don't use a
# permalink, such as search results.
try_files $uri $uri/ /index.php?$args;

# joomla
try_files $uri $uri/ /index.php?q=$uri&$args;

location ~ \.php$ {
  fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name; # if not already defined in the fastcgi_params file
  # any other specific fastcgi_params

WP Super Cache requires a bunch of static file checks. Those are not shown here.




Syntax: error_log file | stderr [ debug | info | notice | warn | error | crit | alert |emerg ]
Default: logs/error.log error
Context: main
Reference: error_log

在学习nginx或者rd环境,将error log等级设置为debug,能够看到nginx处理一个request的详细过程。


nginx是通过fastcgi module与cgi进程通信的,所以该模块相关的配置1,2尤为重要。



fastcgi_hide_header、 fastcgi_pass_header: