VSCode不自动识别系统PATH中的perl，必须显式配置perl.perlPath绝对路径并重启生效；集成终端中perl -v失败即表明环境未就绪，所有Perl功能将静默失效。
VSCode 本身不运行 Perl 脚本，它只是调用你系统里已安装的 perl 可执行文件；如果你在 VSCode 集成终端中连 perl -v 都报 command not found，那所有“运行”“调试”“检查”功能都会静默失效。
为什么在集成终端里 perl 命令找不到
VSCode 启动方式（比如从 Dock、桌面图标或 Windows 快捷方式）通常不加载 shell 的完整 PATH，哪怕你在 iTerm 或 CMD 里能跑 perl -v，VSCode 终端也可能完全看不见它。
- macOS：检查
~/.zshrc是否包含export PATH="/opt/homebrew/bin:$PATH"（对应brew install perl路径），改完后重启 VSCode - Windows：别用普通快捷方式，改用“VS Code (Shell Command)”启动，或手动把
C:Strawberryperlin加进系统环境变量PATH - Linux + perlbrew：确认
source ~/perl5/perlbrew/etc/bashrc已写入~/.bashrc或~/.zshrc，并在 VSCode 终端中执行perlbrew use perl-5.38.0测试
验证方式：打开 VSCode → Ctrl+` 呼出集成终端 → 直接敲 perl -v，必须有输出才算过关。
perl.perlPath 必须写对位置和格式
perl.perlPath 是整个 Perl 开发链的起点，配错就等于没配。它不是可选配置，而是所有扩展（perlcritic、perl-debug、格式化）识别解释器的唯一依据。
- 路径必须是
which perl或where perl输出的**绝对路径**，一字不差："perl.perlPath": "/opt/homebrew/bin/perl"（macOS/Linux）或"perl.perlPath": "C:\Strawberry\perl\bin\perl.exe"（Windows，双反斜杠） - 必须写在
settings.json的**顶层 JSON 对象里**，不能嵌套在"[perl]"块或其他配置块内 - 改完必须**重启 VSCode**——扩展初始化只在启动时读一次这个值，热重载不生效
常见错误：把路径写成 perl（没路径）、/usr/bin/perl（但实际是 /opt/homebrew/bin/perl）、或塞进 "[perl]" 块里导致被忽略。
运行单个 .pl 文件最稳的方式是手动敲命令
VSCode 没有“右键 → Run Perl”的内置按钮，也别依赖 Code Runner 扩展自动推断——它容易用错解释器或忽略 @INC 路径。最可靠、最可控的方式就是自己在集成终端里执行。
- 确保当前打开的是
xxx.pl文件（VSCode 会据此定位工作目录） - 按
Ctrl+`呼出集成终端，它默认cd到当前文件所在目录 - 直接输入：
perl ./xxx.pl（macOS/Linux）或perl .xxx.pl（Windows） - 如果报
Can't locate XXX.pm，临时加模块路径：perl -Ilib ./xxx.pl（lib/是相对路径，按需替换）
注意：./ 和 . 不能省——不加前缀，perl 会去 @INC 里找，而不是当前目录。
launch.json 中 program 字段灰显？先查这两个硬伤
program 字段变灰 = VSCode 根本没认出这是个有效的 Perl 调试配置，90% 情况卡在这两个地方：
- 没装
perl-debug扩展（作者是rcjsuen或gep13，不是rebornix的那个基础 Perl 扩展） -
perl.perlPath没配对，或配了但perl -MDevel::Debug -e 1报错——说明 Perl 解释器虽存在，但缺调试模块
验证调试模块：perl -MDevel::Debug -e 1 不报错才算通过；若失败，运行 cpan install Devel::Debug 安装。最小可用 launch.json 中 program 必须写成 "${file}"，不能写死路径，否则断点不命中。
最容易被忽略的其实是环境变量加载时机——VSCode GUI 启动和终端启动是两套环境，不验证集成终端里的 perl -v 就往下配，后面所有功能都在假跑。
