launchd服务需显式声明绝对路径与环境变量：ProgramArguments必须用which获取的绝对路径，EnvironmentVariables中须补全PATH、LANG、LC_ALL及JAVA_HOME等，避免依赖shell环境。
macos 系统服务（如 launchd 管理的后台进程、自定义 daemon、或需长期运行的 cli 服务）对运行时环境依赖有明确要求：它不继承用户终端的 shell 环境，而是基于 minimal 环境启动，因此 path、语言变量、homebrew 安装路径、甚至 python/node.js 的可执行位置都可能不可用。配置关键在于显式声明依赖路径、避免隐式假设，并统一管理启动上下文。
确保 launchd 能正确找到命令和依赖
launchd 是 macOS 管理系统级和服务级进程的核心，其 plist 配置中 ProgramArguments 或 Program 指定的二进制必须是绝对路径；相对路径、别名、shell 函数均无效。
- 用
which node、which python3、which java查出真实路径（例如/opt/homebrew/bin/node或/usr/bin/python3），直接写入 plist - 若依赖 Homebrew 安装的工具（如
jq、curl、git），同样用which获取路径，不要依赖/usr/bin下旧版本 - 避免在 plist 中调用
sh -c "xxx"执行复杂命令——容易因 shell 差异或未加载 profile 导致失败
显式设置环境变量（PATH 最关键）
launchd 默认 PATH 极简（通常只有 /usr/bin:/bin:/usr/sbin:/sbin），Homebrew、SDKMAN、pyenv、nvm 等路径均不在其中。
- 在 plist 的
EnvironmentVariables字典中手动补全 PATH，例如：
PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" - 若项目依赖特定 Python 环境（如 venv 或 pyenv），需额外指定
PYTHONPATH和PATH，并确保 venv 的bin/在 PATH 前置位 - Java 服务需显式设
JAVA_HOME：用/usr/libexec/java_home -v 17获取路径后填入
处理语言与编码依赖（防止 Unicode 错误）
某些脚本（尤其是 Python、Ruby）在无 locale 环境下会 fallback 到 ASCII，导致中文路径、日志输出、HTTP 响应解析失败。
- 在 plist 的
EnvironmentVariables中加入：
LANG="en_US.UTF-8"
LC_ALL="en_US.UTF-8" - 验证方式：在服务脚本开头加
locale命令输出，确认LC_CTYPE和LANG已生效 - macOS 默认不生成 locale 文件，如需自定义 locale，可用
localedef生成（但通常 en_US.UTF-8 已内置）
验证与调试技巧（快速定位环境缺失）
服务启动失败常表现为 silent exit 或日志中 “command not found” / “No module named xxx”。调试不能只看终端能否运行，而要看 launchd 实际环境。
- 临时改用
StandardOutPath和StandardErrorPath输出日志到文件，再tail -f观察 - 在脚本第一行插入
env >& /tmp/my-service-env.log，查看真实环境变量快照 - 用
launchctl kickstart -k system/your.service强制重启并捕获即时错误（比sudo systemctl更贴合 macOS 机制） - 测试前先用
launchctl list | grep your.service确认是否已加载，用launchctl print system/your.service查看完整配置快照
