macos项目本地脚本执行失败主因是环境链断裂，需三步排查：确认终端正确识别node/npm路径、检查脚本执行权限与lf换行符、绕过shell安全限制（如nvm未加载或path缺失）。
macos 上项目本地脚本（如 npm run dev、./scripts/build.sh 或 npx xxx）无法执行，多数不是脚本本身写错了，而是环境链断在了“识别”或“允许运行”环节。重点排查三个层面：node/npm 是否真被终端识别、脚本是否有执行权限、以及是否被 shell 安全策略拦截。
确认终端能真正调用 node 和 npm
VSCode 内置终端、iTerm2、系统终端有时加载的环境变量不一致。先验证当前终端是否真的“知道” node：
- 在出问题的终端里直接运行
which node和which npm，看是否返回有效路径（如/opt/homebrew/bin/node或~/.nvm/versions/node/v20.12.0/bin/node） - 如果返回空，说明 PATH 没生效。不要只依赖
node -v成功就认为没问题——有些 IDE 会偷偷注入 PATH，但真实 shell 并未加载 - 检查你用的是 zsh 还是 bash：macOS Catalina 及以后默认是 zsh，应编辑
~/.zshrc（不是.bash_profile），追加类似这行：export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH" - 改完后执行
source ~/.zshrc，再新开一个终端测试
检查本地脚本的执行权限和换行符
macOS 是 Unix 系统，对可执行文件有明确权限要求：
- 如果是自定义 shell 脚本（如
./build.sh），确保它有x权限：chmod +x ./build.sh - 检查文件换行符是否为 LF（Unix 风格）：Windows 编辑器保存可能带 CRLF，导致解析失败。
可用file ./build.sh查看，或用 VSCode 右下角切换换行符为 LF - package.json 中的 scripts 命令（如
"dev": "node server.js"）无需 chmod，但若用了#!/usr/bin/env node开头的 JS 文件，要确保该文件本身可读且无 BOM 头
绕过 shell 安全限制（尤其使用 nvm 或自定义 bin 目录时）
某些 CLI 工具（如 npx、vue-cli-service）本质是通过 Node 启动的包装脚本，但 macOS 的 shell 可能因路径未登录态加载而找不到它们：
- 在终端中启动 HBuilderX 或 VSCode：运行
open -a "HBuilderX"或code .，而不是从 Dock 或 Finder 点击打开——这样能继承当前 shell 的完整环境 - 如果用了 nvm，在
~/.zshrc中确保 nvm 加载逻辑放在最前面，并且包含nvm use --silent（自动启用默认版本） - 对于全局安装的命令（如
uniapp-cli）仍报command not found，运行npm config get prefix查看全局 bin 路径，再把它显式加进 PATH：export PATH="$(npm config get prefix)/bin:$PATH"
补充：常见干扰项快速排除
这些情况看似无关，却常导致脚本静默失败：
- 项目路径含中文或空格（如
/Users/xxx/我的项目/）：部分 CLI 对路径编码敏感，建议移到纯英文路径下测试 - OneDrive 或 iCloud 同步目录：文件可能被锁或元数据异常，临时移出同步文件夹再试
- Node.js 版本过高引发 OpenSSL 兼容问题（老项目）：在项目根目录运行
export NODE_OPTIONS=--openssl-legacy-provider，再执行脚本 - 终端类型设为“login shell”：VSCode 设置中搜索
terminal.integrated.shellArgs，设为["-l"]，确保加载完整 profile
