庆祝 nginx 诞生 20 周年！阅读我们最新的博客，了解我们的历程和里程碑 最新博客。

模块 ngx_http_perl_module

已知问题 示例配置 指令      perl      perl_modules      perl_require      perl_set 从 SSI 调用 Perl $r 请求对象方法

ngx_http_perl_module 模块用于在 Perl 中实现 location 和变量处理器，并将 Perl 调用插入到 SSI 中。

此模块默认情况下未构建，应使用--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 模块也必须重新构建——它们将无法与新的 Perl 一起使用。

每次重新配置后，主进程和工作进程的大小都可能会增加。如果主进程的大小增长到不可接受的程度，则可以在不更改可执行文件的情况下应用 实时升级 过程。

当 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<br/>");

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

    return OK;
}

1;
__END__

指令

为给定的 location 设置 Perl 处理程序。

为 Perl 模块设置额外的路径。

定义每次重新配置时将加载的模块的名称。可以存在多个perl_require 指令。

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

从 SSI 调用 Perl

调用 Perl 的 SSI 命令具有以下格式

<!--# perl sub="module::function" arg="parameter1" arg="parameter2" ...
-->

$r 请求对象方法

$r->args

返回请求参数。

$r->filename

返回对应于请求 URI 的文件名。

$r->has_request_body(处理器)

如果请求中没有主体，则返回 0。如果有主体，则为请求设置指定的处理器并返回 1。读取请求主体后，nginx 将调用指定的处理器。请注意，处理器函数应通过引用传递。示例

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, "\"<br/>");
    $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n");

    return OK;
}

1;

__END__

$r->allow_ranges

启用在发送响应时使用字节范围。

$r->discard_request_body

指示 nginx 丢弃请求主体。

$r->header_in(字段)

返回指定客户端请求标头字段的值。

$r->header_only

确定是否应将整个响应或仅其标头发送到客户端。

$r->header_out(字段, 值)

为指定的响应标头字段设置值。

$r->internal_redirect(uri)

内部重定向到指定的uri。实际重定向发生在 Perl 处理程序执行完成后。

从 1.17.2 版本开始，该方法接受转义的 URI 并支持重定向到命名 location。

$r->log_error(错误号, 消息)

将指定的消息写入 error_log。如果错误号 非零，则错误代码及其描述将附加到消息中。

$r->print(文本, ...)

将数据传递给客户端。

$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(名称[, 偏移量[, 长度]])

将指定的文件内容发送到客户端。可选参数指定要传输的数据的初始偏移量和长度。实际数据传输发生在 Perl 处理程序完成后。

$r->send_http_header([类型])

将响应标头发送到客户端。可选的类型 参数设置“Content-Type”响应标头字段的值。如果该值为一个空字符串，则不会发送“Content-Type”标头字段。

$r->status(代码)

设置响应代码。

$r->sleep(毫秒, 处理器)

设置指定的处理器并停止请求处理指定时间。在此期间，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(文本)

解码以“%XX”形式编码的文本。

$r->uri

返回请求 URI。

$r->variable(名称[, 值])

返回或设置指定变量的值。变量对于每个请求都是本地的。