Docker环境下Nginx调用Perl脚本出现500错误的排查求助

算力阿峰

2026-7-4

Nginx Perl模块500错误原因及解决办法

核心错误原因

你在nginx.conf的location中使用perl rewrite.pl;是错误语法。Nginx的Perl模块要求perl指令后填写脚本中定义的子例程（函数）名称，而非脚本文件名。报错信息Undefined subroutine &main::rewrite.pl明确说明：Nginx将rewrite.pl当作子例程名去查找，自然找不到对应定义，导致500错误。

解决步骤

1. 修改Perl脚本，定义子例程

编辑rewrite.pl，添加一个符合Nginx Perl模块规范的处理子例程（比如命名为handler）：

sub handler {
    my $r = shift;
    # 设置响应头
    $r->send_http_header('text/plain');
    # 如果只是请求头，直接返回OK
    return OK if $r->header_only;
    # 输出响应内容
    $r->print("Hello from Perl script!");
    return OK;
}

2. 修正nginx.conf配置

需要先通过perl_require指令加载脚本文件，再在location中调用子例程：

http {
   perl_modules perl/lib;
   # 加载Perl脚本（可写绝对路径避免路径问题）
   perl_require /etc/nginx/rewrite.pl;
   server {
      listen 80;

      location /hello/world {
          # 调用脚本中定义的handler子例程
          perl handler;
      }
   }
}

3. 确认Docker挂载路径匹配

当前docker-compose将rewrite.pl挂载到/etc/nginx/rewrite.pl，确保nginx.conf中的perl_require路径和这个挂载路径一致（上面的配置已经用了绝对路径，无需调整挂载）。如果要使用相对路径，需要把脚本挂载到perl_modules指定的目录下，比如：

nginx:
  image: nginx:perl
  ports:
    - "8080:80"
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf
    - ./rewrite.pl:/etc/nginx/perl/lib/rewrite.pl

此时nginx.conf中的perl_require可以简化为perl_require rewrite.pl;。