CPAN安装失败主因是系统未预装cpan命令，需按发行版安装对应包；交互卡顿应加-f参数或改用cpanm；模块找不到需检查@INC并设置PERL5LIB；依赖C库的模块须先装系统开发包。
CPAN 安装失败：提示 No such file or directory: cpan
说明系统没装 cpan 命令本身，不是模块问题。Perl 自带 cpan，但某些精简版 Linux（如 Alpine、部分 Docker 镜像）或手动编译 Perl 时可能漏掉。
- Debian/Ubuntu：运行
sudo apt install perl-modules-5.36（版本号按实际 Perl 版本调整，可用perl -v查） - CentOS/RHEL：运行
sudo yum install perl-core或sudo dnf install perl-core - Alpine：运行
apk add perl-app-cpanminus（推荐改用cpanm，见下节） - 确认安装成功：执行
cpan -V，能看到配置摘要才算到位
cpan 安装卡在 *** Module::AutoInstall version 1.06 或反复问 yes/no
这是交互式默认行为，尤其遇到依赖多、需编译的模块（如 DBD::mysql）时特别明显。它不报错，但停住不动，容易误判为卡死。
- 加
-f强制跳过确认：cpan -f Some::Module - 更彻底的办法是提前配置非交互模式：
echo "prerequisites_policy follow" | cpan -i，或直接写入~/.cpan/CPAN/MyConfig.pm - 生产环境建议换用
cpanm（cpanminus）：它默认静默、无配置文件、速度快，安装命令是cpanm Some::Module - 注意：
cpanm不自带，需先用系统包管理器或curl -L https://cpanmin.us | perl - --self-upgrade装好
安装后 use Some::Module 仍报 Can't locate Some/Module.pm
模块确实装了，但 Perl 找不到路径。常见于非 root 用户安装、自定义 local::lib、或混用系统 Perl 和 perlbrew。
- 查模块真实位置：
perldoc -l Some::Module（返回路径说明已安装） - 查 Perl 的
@INC（搜索路径）：perl -MConfig -e 'print "$_\n" for @Config{qw@inc@}'或perl -E 'say for @INC' - 如果模块在
/home/user/perl5/lib/perl5/，但该路径不在@INC中，需补上：export PERL5LIB="/home/user/perl5/lib/perl5:$PERL5LIB"，并写入~/.bashrc - 用
local::lib的话，确保每次 shell 启动都执行了eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"
为什么 DBD::Pg 或 XML::LibXML 死活装不上？
这类模块依赖外部 C 库，cpan 只负责 Perl 层，不处理系统级依赖。错误日志里通常有 cannot find -lpq 或 xml2-config not found 这类线索。
-
DBD::Pg需要 PostgreSQL 客户端开发包：sudo apt install libpq-dev（Debian）或sudo yum install postgresql-devel（RHEL） -
XML::LibXML需要libxml2和libxslt开发头文件：sudo apt install libxml2-dev libxslt1-dev或sudo yum install libxml2-devel libxslt-devel - 装完系统依赖后，别忘了清理缓存再试：
cpan -t Some::Module测试前先cpan -f -i Some::Module强制重装 - Mac 用户注意：
brew install libxml2后可能需额外设XMLPREFIX环境变量，否则找不到头文件
路径和权限经常串在一起出问题——比如 root 装的模块普通用户用不了，或者 perlbrew 切换后 cpan 还在用系统 Perl 的配置。动手前先 which perl 和 which cpan 对齐一次，省掉大半排查时间。
