为何perl的pod2usage(-verbose =>2)显示源代码而非格式化文档？

这个问题我之前也碰到过，核心原因就是系统里缺了perldoc工具——也就是perl-doc包没装，导致Pod::Usage没法调用它来把POD文档转换成格式化的手册页，只能直接输出原始的代码和POD内容，同时弹出「您需要安装perl-doc软件包才能使用此程序」的提示。

下面给你几个可行的解决方案：

1. 安装perl-doc包（推荐） #

根据你的操作系统，执行对应的安装命令：

• Debian/Ubuntu 系列：

  sudo apt-get install perl-doc
  

• RHEL/CentOS 系列：

  sudo yum install perl-doc
  

• macOS（使用Homebrew的情况，若系统自带perl缺失perldoc）：

  brew install perl
  

安装完成后再运行你的脚本，pod2usage(-verbose=>2)就能正常输出格式化的完整手册页了。

2. 不依赖perldoc，让Pod::Usage自行格式化 #

如果暂时没法安装perl-doc，或者想绕开外部工具依赖，可以给pod2usage添加-noperldoc参数，强制它用Perl内置的POD解析器生成输出：

use Pod::Usage qw(pod2usage);
pod2usage(-verbose => 2, -noperldoc => 1);

__END__
=head1 NAME
Minimal example

=head1 SYNOPSIS
This is the synopsys section.
=cut

这个参数会让Pod::Usage跳过调用外部的perldoc，直接自己处理POD文档的格式化，输出效果和perldoc生成的几乎一致。

3. 手动指定perldoc路径（如果已安装但无法调用） #

如果已经装了perl-doc，但Pod::Usage还是找不到perldoc命令，可以手动指定它的绝对路径：

pod2usage(-verbose => 2, -perldoc => '/usr/bin/perldoc');

你可以先用which perldoc命令找到perldoc的实际路径，再替换到上面的参数里。

内容的提问来源于stack exchange，提问作者Matthieu Moy