Nginx本身是一个高性能的静态文件服务器和反向代理，但在某些场景下，我们希望在请求处理的某个环节插入一段自定义逻辑，比如根据请求特征动态计算一个变量、对响应内容做实时改写。虽然OpenResty配合Lua是当下更主流的选择，但Nginx官方源码树里其实自带了一个嵌入式Perl模块——ngx_http_perl_module，它允许直接在配置文件中书写或引用Perl代码，让Perl解释器跑在Nginx的工作进程内部。这篇文章就来完整讲一讲这个模块的原理、编译安装和实际用法。
模块的工作原理与编译安装
ngx_http_perl_module的核心思路是把Perl解释器嵌入到每个Nginx worker进程中。master进程fork出worker后，每个worker都会初始化一个Perl解释器实例，所有注册的Perl代码都在worker进程地址空间内执行，因此调用开销非常低，不存在外部CGI那样的进程创建成本。这也是它和传统perl-cgi或者fastcgi方案的最大的区别：代码不是在独立进程中运行，而是与Nginx事件循环共享同一个进程。
这个模块默认不会编译进Nginx，需要在configure阶段显式开启，并且要求系统上装有Perl开发头文件。以源码编译为例，典型的configure命令如下：
# 安装Perl开发库（以Debian/Ubuntu为例）
apt-get install libperl-dev
# 解压Nginx源码后执行configure
./configure \
--prefix=/usr/local/nginx \
--with-http_perl_module \
--with-http_ssl_module
make && make install
编译完成后，可以用/usr/local/nginx/sbin/nginx -V查看编译参数，确认输出中包含--with-http_perl_module。需要注意的一点是，模块对Perl版本有一定要求，过老的Perl（如5.8以前）可能编译失败，建议使用系统自带的较新版本Perl。如果使用的是操作系统仓库中的Nginx包，一些发行版会提供独立的nginx-module-perl子包，直接安装即可，无需自己编译。
两种典型用法：perl_set与location handler
模块提供了三个主要指令：perl_modules用于指定Perl模块的搜索路径，perl_require用于加载Perl模块文件，perl_set用于在配置中定义一个由Perl代码计算的Nginx变量。此外还可以在location中通过perl指令直接指定一个Perl handler来处理整个请求。先看perl_set的例子：
http {
perl_set $client_signature '
sub {
my $r = shift;
# 根据请求头计算一个变量
my $ua = $r->header_in("User-Agent") || "unknown";
if ($ua =~ /Mobile/) {
return "mobile-" . $r->remote_addr;
}
return "desktop-" . $r->remote_addr;
}
';
server {
listen 80;
location /track {
# 这个变量在日志中可以直接引用
log_format sig '$client_signature $request';
return 200 "sig=$client_signature\n";
}
}
}
上面代码里的$r是模块传递给Perl子例程的请求对象，通过它可以读取请求头、URI、请求方法等信息。注意perl_set定义的变量是惰性求值的，只有在被真正引用时才会执行Perl代码，这一点和Nginx其他变量的行为一致，不会白白浪费CPU。
第二种用法是把整个location的处理交给Perl函数，这适合实现一些轻量的动态接口：
http {
perl_modules perl/lib;
perl_require myapp.pm;
server {
listen 80;
location /hello {
perl myapp::handler;
}
}
}
对应的perl/lib/myapp.pm文件内容如下：
package myapp;
use nginx;
sub handler {
my $r = shift;
# 设置响应头
$r->send_http_header("text/html; charset=utf-8");
return OK if $r->header_only;
# 输出响应体
$r->print("hello from embedded perl\n");
$r->rflush;
return OK;
}
1;
这里必须use nginx;来引入模块内置的方法。$r->print负责输出内容，返回值OK是Nginx::Constant中导出的常量，表示请求处理成功结束。handler模式的好处是整个响应生命周期都由Perl代码掌控，可以配合$r->has_request_body读取POST body，也可以用$r->internal_redirect在Perl内部发起内部跳转，将请求转交给其他location处理。
进阶能力与使用限制
除了定义变量和处理请求，这个模块还支持响应体过滤和子请求。$r->sendfile可以直接发送文件内容，$r->sleep配合定时器可以实现延时处理。如果需要访问数据库或外部服务，模块也内置了非阻塞的socket支持，写法上类似Perl的事件编程。不过实际使用中更常见的做法是把Perl逻辑控制在很小的范围内，比如仅做变量计算和轻量校验，重量级的业务逻辑仍然交给后端服务。
必须正视的是这个模块的几个限制。第一，Perl代码在worker启动时加载后就常驻内存，修改代码后需要重启Nginx或者利用HUP信号热加载才能生效，调试体验不如外部脚本方便。第二，由于代码跑在worker进程内，任何段错误或致命错误都可能导致整个worker崩溃，虽然master会自动拉起新worker，但期间的请求会受影响，因此代码中要严格使用eval包裹可能出错的操作。第三，绝不能在Perl代码中执行长时间阻塞的操作，比如同步的数据库查询或sleep调用，这会卡住worker的事件循环，直接拖垮该进程上的所有并发连接。
从适用场景来看，如果只是需要动态计算变量、做简单的请求改写或轻量API，ngx_http_perl_module完全够用且足够轻量；如果逻辑复杂、需要协程和高并发访问外部资源，那么选择OpenResty加Lua会更加稳妥。理解了模块的进程模型和这些边界条件，就能放心地把它用在对的地方。
Nginxngx_http_perl_modulePerl脚本修改时间：2026-09-08 12:00:41