zai-org / zai-org/feedback

[Bug] macOS: node-pty spawn-helper 缺少执行位,内置终端每次更新后无法启动(3.11.2 / 3.12.1 均复现)

Open
#663 1 comment 0 reactions 0 assignees View on GitHub

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)。

复现步骤

  1. 将 ZCode 安装/更新到 /Applications(bundle 属主 root:wheel);
  2. 打开内置终端 → 出现上述报错;
  3. sudo chmod +x <该路径> 后恢复正常,直到下次更新再次复现。

建议修复

  1. 打包时确保 app.asar.unpacked 中需要执行位的文件(至少 node-pty 的 spawn-helper)带上 0755(疑似打包/拷贝环节丢失了 POSIX 权限位);
  2. 参考: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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.