[Bug] macOS: node-pty spawn-helper 缺少执行位,内置终端每次更新后无法启动(3.11.2 / 3.12.1 均复现)
Open
Nobody has claimed this yet.
priority: P2
- Dominant language
- No language data
- Stars
- 22
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
环境
- macOS 27.0(Build 26A428),Apple Silicon
- ZCode 3.12.1(macOS 桌面版;3.11.2 存在同样问题)
- 安装位置:/Applications/ZCode.app(bundle 属主 root:wheel)
现象
内置终端无法启动,提示:
[Terminal failed to start]
node-pty spawn-helper is not executable: /Applications/ZCode.app/Contents/Resources/app.asar.unpacked/node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper. EPERM: operation not permitted, chmod '/Applications/ZCode.app/Contents/Resources/app.asar.unpacked/node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper'
原因分析
- 该文件在发布包内没有执行位:
$ ls -l .../prebuilds/darwin-arm64/spawn-helper -rw-r--r-- 1 root wheel 69216 spawn-helper - 报错里的 EPERM chmod 其实是 node-pty 的自动修复动作:它检测到文件不可执行后会尝试 chmod,但 app bundle 属主是 root:wheel,普通用户无权限修改 → 修复失败、终端不可用。
- 每次 ZCode 更新(Squirrel 整包替换)都会重写该文件,权限被重置,因此每次更新后必现。已复现 3 次:2026-08-25、2026-09-04(3.11.2)、2026-09-13(3.12.1)。
复现步骤
- 将 ZCode 安装/更新到 /Applications(bundle 属主 root:wheel);
- 打开内置终端 → 出现上述报错;
sudo chmod +x <该路径>后恢复正常,直到下次更新再次复现。
建议修复
- 打包时确保 app.asar.unpacked 中需要执行位的文件(至少 node-pty 的 spawn-helper)带上 0755(疑似打包/拷贝环节丢失了 POSIX 权限位);
- 参考:VS Code 使用同款 node-pty,其分发包内该 helper 保留了执行位,未出现此问题。
临时绕过
sudo chmod +x "/Applications/ZCode.app/Contents/Resources/app.asar.unpacked/node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper"
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Inspect the packaging or copy step that produces app.asar.unpacked/node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper. Verify that the distributed helper retains 0755 permissions, then install or update the macOS app in /Applications and start the built-in terminal to confirm it works without sudo chmod.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos, node.js
- Domain
- build-system, desktop
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100