先来看一个常见场景：你在 Notepad++ 中编写了一段 Crystal 脚本，满怀信心地按下 F5，结果要么毫无反应，要么弹出提示“不是内部或外部命令”。绝大多数情况下，问题并非出在 Notepad++ 本身，而是 Windows 系统未能找到 crystal 命令——环境变量、路径宏、编码，这三者中只要有一项没有正确对齐，后续操作都将徒劳无功。
crystal --version 在 CMD 中报错，Notepad++ 就无法运行 Crystal 脚本
Notepad++ 本身并不解释代码，它只是将命令交给 cmd 或 PowerShell 去执行。因此，如果终端中连 crystal --version 都无法输出结果，说明系统根本没有识别该命令。
- Crystal 官方 Windows 安装包（例如
crystal-1.12.0-windows-x86_64.zip）解压后，需要手动将其bin目录（如C:\crystal\bin）添加到系统环境变量PATH中 - 添加完成后，务必关闭所有已打开的 CMD/PowerShell 窗口，并重新启动 Notepad++——它仅在启动时读取一次环境变量，仅关闭终端无效
- 不建议仅依赖 Scoop 或 Chocolatey 安装后便认为配置完成，仍需要运行
crystal --version确认正常
Run → Run(F5) 中应填入什么命令才能正确执行 Crystal 脚本
真正隐蔽的陷阱在于路径中包含空格、中文，或者编码未强制设置为 UTF-8。Crystal 默认按 UTF-8 解析源码，但 Windows 控制台默认使用 GBK 编码，一旦遇到非 ASCII 字符就会报 Invalid byte sequence in UTF-8。
- 正确的命令格式为：
cmd /c chcp 65001 >nul && crystal run "$(FULL_CURRENT_PATH)" "$(FULL_CURRENT_PATH)"外面的双引号不可省略，否则路径中若包含空格，crystal只会接收到前半段内容- 切勿写成
crystal run $(FULL_CURRENT_PATH)（缺少引号）或crystal run %FULL_CURRENT_PATH%（那是 CMD 的变量语法，Notepad++ 不识别） - 如果脚本中使用了
gets或STDIN.read，添加-u参数无效——Crystal 不支持该选项。此时可考虑使用 NppExec 的npp_console 1来保持控制台窗口
如何编写稳定的 NppExec 脚本以支持中文输出
NppExec 比 Run 菜单更灵活，尤其适合调试包含 puts 或 print 的脚本，但必须显式处理编码和保存顺序。
- 第一行必须是
NPP_SA VE，否则修改代码后未保存就运行，输出的将是旧版本 - 完整脚本示例：
NPP_SA VE cmd /c chcp 65001 >nul && crystal run "$(FULL_CURRENT_PATH)"
- 不要使用
cd切换目录后再执行——Crystal 的require和相对路径依赖当前工作目录，而$(CURRENT_DIRECTORY)不一定等于文件所在目录。直接使用"$(FULL_CURRENT_PATH)"最为稳妥，它已包含绝对路径 - 如果脚本编译后需要生成可执行文件（例如
crystal build），注意$(NAME_PART)是小写，而非$(NAME_part)，写错将找不到输出文件
中文路径或文件名导致 crystal run 失败该如何解决
Crystal 解析器本身支持 UTF-8 路径，但 Windows 的 CreateProcess API 在旧版 CRT 下对宽字符路径支持不稳定，Notepad++ 调用 cmd 时容易传参失败。
- 首选方案：将脚本移至纯英文路径下，例如
C:\dev\crystal\hello.cr - 次选方案：改用 Python Script 插件，通过
subprocess.run绕过 cmd 层，直接调用crystal进程（前提是已安装 Python） - 若要强行使用中文路径，可尝试
cmd /u /c，同时确保 Notepad++ 当前编码为 UTF-8（菜单栏「格式」→「转为 UTF-8 编码」），但成功率不足 70%，不建议在生产环境中冒险
请记住，整个配置流程中最为关键的环节只有一个：crystal 命令是否能够被系统正确识别。这一前提若不成立，后续所有路径宏、编码切换、NppExec 保存指令都将毫无意义。先确认这一点，后续步骤才会更加顺畅。
