排查macOS Homebrew Perl模块问题，核心是确认“谁在用哪个Perl”及“模块装到哪”：先用which perl、perl -v、perl -MConfig -e 'print $Config{installsitearch}'验证Perl路径与模块目录；再用perldoc -l或perl -MModule::Name -e 'print "loaded"'检查模块是否真在对应路径；避免混用perlbrew、系统Perl等不同环境，确保@INC包含Homebrew的site_perl路径。
排查 macos 上 homebrew 安装的 perl 模块问题，核心是理清“谁在用哪个 perl”和“模块装到了哪里”。很多人遇到 can't locate xxx.pm 或 undefined symbol 错误，不是模块没装，而是 perl 解释器和模块路径不匹配。
确认当前使用的 Perl 是 Homebrew 版本
Apple Silicon（M1/M2/M3）默认路径是 /opt/homebrew/bin/perl，Intel 是 /usr/local/bin/perl。运行以下命令验证：
-
which perl—— 看输出是否为 Homebrew 路径 -
perl -v—— 确认版本号（如 5.38.0），并注意末尾是否带(with Homebrew)或类似提示 -
perl -MConfig -e 'print $Config{installsitearch},"\n"'—— 查看该 Perl 实际安装模块的目录（比如/opt/homebrew/lib/perl5/site_perl/5.38）
检查模块是否真被安装到对应 Perl 的路径下
Homebrew 安装的 Perl 模块（如用 cpan 或 cpanm）默认会写入上面查出的 installsitearch 目录。别只看 ~/.cpan 或系统 Perl 的 /Library/Perl。
- 用
perldoc -l Module::Name查找模块物理路径（例如perldoc -l JSON） - 若返回
No documentation found，但模块实际存在，说明文档未生成；可改用perl -MModule::Name -e 'print "loaded\n"'测试加载 - 手动进入
installsitearch目录，用ls -R | grep ModuleName确认文件是否存在
避免混用不同 Perl 环境的模块
如果你同时用了 perlbrew、plenv 或系统自带 Perl，它们的 @INC（模块搜索路径）互不相通。一个模块在 perlbrew 下装了，在 Homebrew Perl 下就不可见。
- 运行
perl -E 'say for @INC'，确认输出中包含 Homebrew 的site_perl和vendor_perl路径，不含~/perl5或/Library/Perl - 不要在 Homebrew Perl 下执行
source ~/perl5/perlbrew/etc/bashrc，否则会覆盖PATH和@INC - 如果必须共存，建议统一用
cpanm --local-lib=~/perl5并配合PERL5LIB，但需手动管理，不推荐新手
修复常见报错示例
遇到具体错误时，按这个顺序快速定位：
-
Can't locate XXX.pm in @INC→ 先跑perl -E 'say for @INC'，再查模块是否在其中任一目录下 -
Undefined symbol: SSL_connect→ 很可能是模块链接了系统 OpenSSL，而 Homebrew Perl 用的是openssl@3；重装模块：brew reinstall perl后再cpanm --force --notest XXX -
Permission denied写入/opt/homebrew/lib/perl5→ 不要用sudo cpan；确保当前用户对/opt/homebrew有读写权限：sudo chown -R $(whoami) /opt/homebrew
