标签： 官方文档

该模块默认不会构建，需要通过–with-http_perl_module参数配置。
该模块需要Perl版本5.6.1或更高。C编译器需要匹配构建Perl。

已知问题
该模块是实验性的。
重新编译Perl时，需要使用-Dusemultiplicity=yes或-Dusethreads=yes参数。同时，为了是Perl运行时占用更少的内存，应该使用-Dusemymalloc=no参数。为检测当前构建的Perl的参数，运行：

$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';

注意，通过-Dusemultiplicity=yes或-Dusethreads=yes参数重新构建Perl后，所有二进制Perl模块必须一同重新构建。
在每次重新配置后，主进程和工作进程的大小可能会增长。如果主进程增长到不可接受的大小，live upgrade程序可以不改变可执行文件。
当Perl模块执行长时间的任务，例如解析一个域名、连接其他服务器或查询数据库，分配给当前工作进程的其他请求不会被处理。因此建议只有确定耗时短的操作被执行，例如访问本地文件系统。

示例配置

http {

    perl_modules perl/lib;
    perl_require hello.pm;

    perl_set $msie6 '

        sub {
            my $r = shift;
            my $ua = $r->header_in("User-Agent");

            return "" if $ua =~ /Opera/;
            return "1" if $ua =~ / MSIE [6-9]\.\d+/;
            return "";
        }

    ';

    server {
        location / {
            perl hello::handler;
        }
    }

perl/lib/hello.pm模块：

package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->send_http_header("text/html");
    return OK if $r->header_only;

    $r->print("hello!\n
");

    if (-f $r->filename or -d _) {
        $r->print($r->uri, " exists!\n");
    }

    return OK;
}

1;
__END__

perl

语法：perl module::function|’sub { … }’
默认：—
上下文：location, limit_except

设置给定location的Perl处理器。

perl_modules

语法：perl_modules path
默认：—
上下文：http

为Perl模块添加额外的路径。

perl_require

语法：perl_require module
默认：—
上下文：http

定义模块名，在每次重配置时加载。可以有多个perl_require指令。

perl_set

语法：perl_set $variable module::function|’sub { … }’
默认：—
上下文：http

为指定的变量安装Perl处理器。

从SSI调用Perl
SSI命令调用Perl有下面的格式：

$r请求对象方法

$r->args
返回请求参数

$r->filename
返回请求URI对应的文件名

$r->has_request_body(handler)
如果请求体内容为空，返回0。如果有请求体，指定的handler将设置请求，并返回1。在读取请求体后，nginx将调用指定的handler。注意handler函数应通过引用传递，例如：

package hello;

use nginx;

sub handler {
    my $r = shift;

    if ($r->request_method ne "POST") {
        return DECLINED;
    }

    if ($r->has_request_body(\&post)) {
        return OK;
    }

    return HTTP_BAD_REQUEST;
}

sub post {
    my $r = shift;

    $r->send_http_header;

    $r->print("request_body: \"", $r->request_body, "\"
");
    $r->print("request_body_file: \"", $r->request_body_file, "\"
\n");

    return OK;
}

1;

__END__

$r->allow_ranges
发送响应时启用byte range功能

$r->discard_request_body
让nginx丢弃请求体

$r->header_in(field)
返回请求头中指定的值

$r->header_only
决定发送客户端完整响应还是只发送头

$r->header_out(field, value)
设置指定的响应头域

$r->internal_redirect(uri)
向指定的uri做内部重定向。重定向发送在Perl处理器执行完毕。
重定向到名称location目前不支持。

$r->log_error(errno, message)
写指定的信息到error_log。如果errno非零，错误码和描述信息将被追加到信息中。

$r->print(text, …)
发送数据到客户端。

$r->request_body
如果请求体没有写入临时文件，则返回请求体。确保客户端请求体在内存中，大小需要被client_max_body_size指令限制，并且需要通过client_body_buffer_size指令设置足够大的缓冲区。

$r->request_body_file
返回客户端请求体文件的名称。在处理后，文件会被移除。需要使用client_body_in_file_only指令确保请求体总会写到文件中。

$r->request_method
返回客户端请求的HTTP方法

$r->remote_addr
返回客户端IP地址

$r->flush
立即发送数据到客户端

$r->sendfile(name[, offset[, length]])
发送指定的文件内容到客户端。可选参数定义了初始的偏移和要传输数据的长度。实际的传输发生在Perl处理器完成时。

$r->send_http_header([type])
发送响应头到客户端。可选参数type这只了响应头域“Content-Type”。如果值是一个空字符串，“Content-Type”不会被设置。

$r->status(code)
设置响应码

$r->sleep(milliseconds, handler)
设置滴定的处理器，并暂停处理请求指定的时间。与此同时，nginx处理其他的请求，在指定时间过后，nginx将会调用安装的处理器。注意处理器函数需要通过引用传递。为在处理器之间传递数据，需要使用$r->variable()，例如：

package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->discard_request_body;
    $r->variable("var", "OK");
    $r->sleep(1000, \&next);

    return OK;
}

sub next {
    my $r = shift;

    $r->send_http_header;
    $r->print($r->variable("var"));

    return OK;
}

1;

__END__

$r->unescape(text)
解码一个“%XX”格式的文本

$r->uri
返回请求URI

$r->variable(name[, value])
返回或设置指定变量的值。变量对每一个请求都是本地的。

伪流媒体与兼容的Flash播放器一同工作。播放器发送给服务器一个带有指定开始时间的查询字符串参数（名称为start，定义为秒数）的请求，服务器响应指定查询开始时间的流，例如：
http://example.com/elephants_dream.mp4?start=238.88
这允许在任何时候执行随机搜索，或在时间线中间开始回放。
为了支持搜索，基于H.264格式存储媒体信息到一个所谓的“moov atom”中。这是文件中的一部分，保存整个文件的信息索引。
为了开始回放，播放器首先需要读取媒体信息。这需要发送一个带着start=0参数特殊的请求。很多编码软件将媒体信息插入到文件结尾。这对伪流媒体是不好的，因为播放器需要下载整个文件后才能播放。如果媒体信息在文件开头，对nginx来说就很方便的开始发送后面的文件内容。如果媒体信息放在文件结尾，nginx必须读取整个文件并准备一个新流，以便媒体信息出现在媒体数据之前。这涉及一些CPU内存及磁盘I/O的开销，所以建议提前为伪流媒体准备一个源文件，这样要比每个请求nginx去做这件事要好。
模块同时支持HTTP请求的end参数（1.5.13+），可以设置播放结束点。end参数可以同start定义也可以分开定义：
http://example.com/elephants_dream.mp4?start=238.88&end=555.55
为了匹配非零的start或end参数的请求，nginx将会从文件中读取媒体信息，准备含有请求时间段内的流，并发送给客户端。这与上面说的有同样的开销。
如果请求没有包含start和end参数，就没有额外开销，文件只是简单的作为静态资源发送。一些播放器还支持byte-range请求，因此不需要这个模块。
这个模块默认不会构建，需要通过–with-http_mp4_module参数开启。
如果第三方mp4模块之前使用过，该模块应该禁用。
简单的flv伪流媒体支持通过ngx_http_flv_module模块提供。

示例配置

location /video/ {
    mp4;
    mp4_buffer_size       1m;
    mp4_max_buffer_size   5m;
    mp4_limit_rate        on;
    mp4_limit_rate_after  30s;
}

mp4

语法：mp4
默认：—
上下文：location

在location块内开启模块功能。

mp4_buffer_size

语法：mp4_buffer_size size
默认：mp4_buffer_size 512K
上下文：http, server, location

设置用于处理MP4文件的初始缓冲区大小。

mp4_max_buffer_size

语法：mp4_max_buffer_size size
默认：mp4_max_buffer_size 10M
上下文：http, server, location

在处理媒体信息的过程中，一个更大的缓冲区是有必要的。它的大小不能超过指定的大小，否则nginx将返回500错误码，并记录下面的信息：

"/some/movie/file.mp4" mp4 moov atom is too large:
12583268, you may want to increase mp4_max_buffer_size

mp4_limit_rate

语法：mp4_limit_rate on | off | factor
默认：mp4_limit_rate off
上下文：http, server, location

限制传输给客户端响应的速率。这个限速基于MP4文件的平均比特率。为了计算这个速率，比特率会乘以定义的factor（因数）。特殊值“on”为因数1.1。特殊值“off”禁用限速。限制是针对每个请求的，所以如果客户端同时打开两个连接，则总速率为两倍设置的值。
该指令对商业版本可用。

mp4_limit_rate_after

语法：mp4_limit_rate_after time
默认：mp4_limit_rate_after 60s
上下文：http, server, location

设置初始的媒体数据大小（以时间为单位），超过这个值后响应将会被限速。
该指令对商业版本可用。