Dist::Zilla构建CPAN分发时MetaCPAN中Pod跨文件链接失效求助

Pod链接解析与MetaCPAN的关联逻辑 #

• 本地perldoc会自动遍历@INC路径，匹配模块名对应的.pm或.pod文件，不管后缀，所以你本地执行perldoc ODF::lpOD_Helper::Unicode能正常显示内容。
• MetaCPAN生成HTML链接时，依赖分发包的元数据文件（META.json/META.yml）里的provides字段——这个字段定义了每个模块名对应的实际文件路径。如果你的分发元数据里没有ODF::lpOD_Helper::Unicode的条目，MetaCPAN就无法把模块名映射到对应的.pod文件，生成的链接自然没有后缀，访问就会404。
• 像ODF::lpOD这类正常的分发，它们的META文件里的provides字段正确包含了ODF::lpOD::Tutorial对应的.pod文件路径，所以MetaCPAN能生成带.pod后缀的有效链接。

用Dist::Zilla添加正确的元信息 #

要让Dist::Zilla自动生成正确的provides字段，推荐用以下几种方法：

方法1：使用MetaProvides::Package插件 #

这个插件会自动扫描你的代码和文档文件，生成provides条目。只需在dist.ini中添加：

[MetaProvides::Package]
include_pod = 1

其中include_pod = 1是关键，它会让插件扫描.pod文件，提取=head1 NAME节里的模块名并加入元数据。

方法2：配合PodWeaver确保Pod格式正确 #

如果你已经在用PodWeaver整理Pod文档，只要确保.pod文件的NAME节正确声明模块名即可。比如lib/ODF/lpOD_Helper/Unicode.pod的开头应该有：

=head1 NAME

ODF::lpOD_Helper::Unicode - 这里写你的模块功能描述

MetaProvides::Package会自动识别这个模块名并关联到对应的.pod文件。

方法3：手动指定provides（不推荐，适合临时场景） #

如果不想用插件，也可以在dist.ini里手动添加：

[MetaProvides]
provides = ODF::lpOD_Helper::Unicode
file = lib/ODF/lpOD_Helper/Unicode.pod

验证与生效 #

生成分发包后，打开META.json文件，确认provides字段包含如下内容：

"provides": {
  "ODF::lpOD_Helper": {
    "file": "lib/ODF/lpOD_Helper.pm"
  },
  "ODF::lpOD_Helper::Unicode": {
    "file": "lib/ODF/lpOD_Helper/Unicode.pod"
  }
}

重新上传到CPAN后，MetaCPAN会同步更新元数据，此时L<ODF::lpOD_Helper::Unicode>生成的HTML链接就会正确指向带.pod后缀的有效地址，404问题就能解决。

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