011、macOS 安装实战Homebrew 加 npm 双途径与常见报错解决从一次深夜翻车说起上周五晚上我正打算用 CodeX 跑一个快速原型结果终端里敲完codex --version等了五秒屏幕只吐出一行冷冰冰的zsh: command not found: codex。当时我第一反应是“又忘了装”但仔细一想昨天明明用 Homebrew 装过。于是开始排查发现 brew 安装的版本被 npm 全局安装的旧版本覆盖了而 npm 那个版本因为 Node 版本不兼容直接罢工。这种“双路径打架”的坑我踩过不止一次。今天这篇笔记就把 macOS 上两种安装方式Homebrew 和 npm的完整流程、避坑点、以及常见报错的根治方法一次性写清楚。环境准备先确认你的 macOS 版本别急着装先看一眼系统版本。CodeX 对 macOS 11 Big Sur 及以上支持最好如果你还在用 Catalina10.15某些依赖库可能会报dyld: Library not loaded的错误。我建议直接升级到 Ventura 或 Sonoma省得后面折腾。打开终端跑一句sw_vers如果看到 ProductVersion 低于 11.0先升级系统别跳过这一步——我见过有人硬扛结果编译时卡在 libxml2 的符号链接上浪费两小时。途径一Homebrew 安装推荐但注意版本锁定Homebrew 是 macOS 上最省心的包管理器前提是你已经装好了 brew。没装的先去官网复制那行安装命令这里不赘述。安装 CodeX 很简单brewinstallcodex装完后验证codex--version如果输出类似codex 2.1.0恭喜你第一步走通了。但这里有个坑Homebrew 默认安装的是最新稳定版但 CodeX 的更新节奏很快有时 brew 仓库里的版本会滞后一两个小版本。如果你需要特定版本比如为了兼容某个插件可以用brewinstallcodex2.0.0# 这里踩过坑版本号要写对否则 brew 会报找不到 formula如果 brew 提示No available formula说明这个版本没进仓库只能换 npm 或者从源码编译。另一个常见问题Homebrew 安装后codex命令找不到。这通常是因为 brew 的 bin 目录没在 PATH 里。检查一下echo$PATH|grep/opt/homebrew/bin如果没输出在~/.zshrc或~/.bash_profile里加上exportPATH/opt/homebrew/bin:$PATH然后source ~/.zshrc。别问我为什么强调这个——我见过三个同事卡在这一步以为装坏了。途径二npm 全局安装灵活但依赖 Node 环境如果你已经在用 Node.js或者需要快速切换 CodeX 版本npm 是更好的选择。前提是你装了 Node建议 v18 以上v16 也能跑但某些新特性会报错。全局安装npminstall-gcodex装完同样验证版本。如果提示npm ERR! code EACCES说明权限不够。别这样写sudonpminstall-gcodex# 不推荐会污染系统权限正确做法是配置 npm 的全局目录到用户目录下mkdir~/.npm-globalnpmconfigsetprefix~/.npm-global然后在~/.zshrc里加exportPATH~/.npm-global/bin:$PATH再重新安装就不会有权限问题了。npm 安装的另一个坑版本冲突。如果你之前用 Homebrew 装过又用 npm 装了一遍系统会优先使用 npm 的版本因为 npm 的 bin 路径通常排在 brew 前面。这会导致你明明 brew 更新了但codex --version还是旧版。解决办法是二选一或者用which codex查看当前用的是哪个路径然后手动删除另一个。双途径共存时的“打架”问题这是最让人头疼的场景。我遇到过的情况是brew 装了 2.1.0npm 装了 2.0.5结果终端里跑的是 2.0.5而且因为 npm 版本依赖的某个库不兼容 macOS Sonoma直接报Segmentation fault。根治方法先决定用哪个途径。我推荐 Homebrew 作为主力因为它不依赖 Node 环境且更新由 brew 统一管理。卸载另一个途径的版本卸载 npm 全局包npm uninstall -g codex或者卸载 brew 包brew uninstall codex清理残留的符号链接whichcodex# 看路径rm-f/usr/local/bin/codex# 如果残留在这里重新安装你选的那个途径然后hash -r刷新命令缓存。如果你非要两个都留着比如测试不同版本可以用npx codex临时调用 npm 版本或者用 brew 的--link和--unlink控制激活哪个。常见报错与解决报错 1dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.70.dylib这个错误通常出现在 Homebrew 安装后原因是 icu4c 库版本不匹配。我遇到时直接跑brew reinstall icu4c brew reinstall codex如果还不行检查一下 brew 的链接brewlink--overwriteicu4c别这样写brew uninstall icu4c然后重装因为很多其他包也依赖它卸载会导致连锁反应。报错 2Error: Cannot find module node:pathnpm 安装后运行时报这个错说明你的 Node 版本太旧低于 v14。CodeX 2.x 要求 Node 16。升级 Nodenvminstall18# 如果你用 nvm# 或者直接下载最新版安装包如果你不想升级 Node可以安装 CodeX 1.x 版本npminstall-gcodex1.9.0但注意1.x 版本功能不全很多新插件不支持。报错 3zsh: killed codex这个最诡异进程直接被系统杀掉。通常是内存不足或者代码签名问题。先检查系统日志log show--predicateeventMessage contains codex--last1h如果看到terminated due to memory pressure说明你的 Mac 内存不够8GB 以下跑大型项目容易触发。解决办法是减少同时运行的应用或者用codex --max-memory 2048限制内存使用。如果是代码签名问题常见于 M1/M2 芯片跑codesign--force--deep--sign- /usr/local/bin/codex# 这里踩过坑需要管理员权限或者直接重新安装让 brew 自动处理签名。报错 4npm ERR! code EINTEGRITYnpm 安装时校验失败通常是网络问题导致包下载损坏。先清缓存npmcache clean--force然后换个镜像源npmconfigsetregistry https://registry.npmmirror.com再重新安装。装完后记得改回官方源否则后续其他包可能出问题npmconfigsetregistry https://registry.npmjs.org个人经验性建议新手无脑选 Homebrew。它帮你处理了依赖、路径、签名出问题也容易回滚。npm 虽然灵活但 Node 版本、权限、缓存问题会让你多花一倍时间。装完后立刻跑一个最小示例。别只验证版本直接codex init创建一个项目然后codex run看看能不能正常启动。我见过有人装完一周后才发现根本跑不起来因为某个动态库没链接。记录你的安装方式。在~/.zshrc里加一行注释比如# CodeX installed via brew on 2024-03-15。半年后你回来维护时会感谢现在的自己。遇到报错先看日志。CodeX 的日志在~/.codex/logs/下错误信息比终端输出详细十倍。别在终端里瞎猜直接tail -f ~/.codex/logs/error.log看实时输出。如果以上都搞不定直接删掉重装。brew uninstall codex然后brew cleanup再重新安装。有时候是 brew 的缓存坏了重装比排查快得多。最后别被这些报错吓到。CodeX 在 macOS 上的稳定性其实不错大部分问题都是环境配置引起的。装好之后你会发现它比很多同类工具都顺手。下一篇我会讲 CodeX 的初始化配置和第一个项目实战到时候见。
011：macOS 安装实战——Homebrew 加 npm 双途径与常见报错解决
011、macOS 安装实战Homebrew 加 npm 双途径与常见报错解决从一次深夜翻车说起上周五晚上我正打算用 CodeX 跑一个快速原型结果终端里敲完codex --version等了五秒屏幕只吐出一行冷冰冰的zsh: command not found: codex。当时我第一反应是“又忘了装”但仔细一想昨天明明用 Homebrew 装过。于是开始排查发现 brew 安装的版本被 npm 全局安装的旧版本覆盖了而 npm 那个版本因为 Node 版本不兼容直接罢工。这种“双路径打架”的坑我踩过不止一次。今天这篇笔记就把 macOS 上两种安装方式Homebrew 和 npm的完整流程、避坑点、以及常见报错的根治方法一次性写清楚。环境准备先确认你的 macOS 版本别急着装先看一眼系统版本。CodeX 对 macOS 11 Big Sur 及以上支持最好如果你还在用 Catalina10.15某些依赖库可能会报dyld: Library not loaded的错误。我建议直接升级到 Ventura 或 Sonoma省得后面折腾。打开终端跑一句sw_vers如果看到 ProductVersion 低于 11.0先升级系统别跳过这一步——我见过有人硬扛结果编译时卡在 libxml2 的符号链接上浪费两小时。途径一Homebrew 安装推荐但注意版本锁定Homebrew 是 macOS 上最省心的包管理器前提是你已经装好了 brew。没装的先去官网复制那行安装命令这里不赘述。安装 CodeX 很简单brewinstallcodex装完后验证codex--version如果输出类似codex 2.1.0恭喜你第一步走通了。但这里有个坑Homebrew 默认安装的是最新稳定版但 CodeX 的更新节奏很快有时 brew 仓库里的版本会滞后一两个小版本。如果你需要特定版本比如为了兼容某个插件可以用brewinstallcodex2.0.0# 这里踩过坑版本号要写对否则 brew 会报找不到 formula如果 brew 提示No available formula说明这个版本没进仓库只能换 npm 或者从源码编译。另一个常见问题Homebrew 安装后codex命令找不到。这通常是因为 brew 的 bin 目录没在 PATH 里。检查一下echo$PATH|grep/opt/homebrew/bin如果没输出在~/.zshrc或~/.bash_profile里加上exportPATH/opt/homebrew/bin:$PATH然后source ~/.zshrc。别问我为什么强调这个——我见过三个同事卡在这一步以为装坏了。途径二npm 全局安装灵活但依赖 Node 环境如果你已经在用 Node.js或者需要快速切换 CodeX 版本npm 是更好的选择。前提是你装了 Node建议 v18 以上v16 也能跑但某些新特性会报错。全局安装npminstall-gcodex装完同样验证版本。如果提示npm ERR! code EACCES说明权限不够。别这样写sudonpminstall-gcodex# 不推荐会污染系统权限正确做法是配置 npm 的全局目录到用户目录下mkdir~/.npm-globalnpmconfigsetprefix~/.npm-global然后在~/.zshrc里加exportPATH~/.npm-global/bin:$PATH再重新安装就不会有权限问题了。npm 安装的另一个坑版本冲突。如果你之前用 Homebrew 装过又用 npm 装了一遍系统会优先使用 npm 的版本因为 npm 的 bin 路径通常排在 brew 前面。这会导致你明明 brew 更新了但codex --version还是旧版。解决办法是二选一或者用which codex查看当前用的是哪个路径然后手动删除另一个。双途径共存时的“打架”问题这是最让人头疼的场景。我遇到过的情况是brew 装了 2.1.0npm 装了 2.0.5结果终端里跑的是 2.0.5而且因为 npm 版本依赖的某个库不兼容 macOS Sonoma直接报Segmentation fault。根治方法先决定用哪个途径。我推荐 Homebrew 作为主力因为它不依赖 Node 环境且更新由 brew 统一管理。卸载另一个途径的版本卸载 npm 全局包npm uninstall -g codex或者卸载 brew 包brew uninstall codex清理残留的符号链接whichcodex# 看路径rm-f/usr/local/bin/codex# 如果残留在这里重新安装你选的那个途径然后hash -r刷新命令缓存。如果你非要两个都留着比如测试不同版本可以用npx codex临时调用 npm 版本或者用 brew 的--link和--unlink控制激活哪个。常见报错与解决报错 1dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.70.dylib这个错误通常出现在 Homebrew 安装后原因是 icu4c 库版本不匹配。我遇到时直接跑brew reinstall icu4c brew reinstall codex如果还不行检查一下 brew 的链接brewlink--overwriteicu4c别这样写brew uninstall icu4c然后重装因为很多其他包也依赖它卸载会导致连锁反应。报错 2Error: Cannot find module node:pathnpm 安装后运行时报这个错说明你的 Node 版本太旧低于 v14。CodeX 2.x 要求 Node 16。升级 Nodenvminstall18# 如果你用 nvm# 或者直接下载最新版安装包如果你不想升级 Node可以安装 CodeX 1.x 版本npminstall-gcodex1.9.0但注意1.x 版本功能不全很多新插件不支持。报错 3zsh: killed codex这个最诡异进程直接被系统杀掉。通常是内存不足或者代码签名问题。先检查系统日志log show--predicateeventMessage contains codex--last1h如果看到terminated due to memory pressure说明你的 Mac 内存不够8GB 以下跑大型项目容易触发。解决办法是减少同时运行的应用或者用codex --max-memory 2048限制内存使用。如果是代码签名问题常见于 M1/M2 芯片跑codesign--force--deep--sign- /usr/local/bin/codex# 这里踩过坑需要管理员权限或者直接重新安装让 brew 自动处理签名。报错 4npm ERR! code EINTEGRITYnpm 安装时校验失败通常是网络问题导致包下载损坏。先清缓存npmcache clean--force然后换个镜像源npmconfigsetregistry https://registry.npmmirror.com再重新安装。装完后记得改回官方源否则后续其他包可能出问题npmconfigsetregistry https://registry.npmjs.org个人经验性建议新手无脑选 Homebrew。它帮你处理了依赖、路径、签名出问题也容易回滚。npm 虽然灵活但 Node 版本、权限、缓存问题会让你多花一倍时间。装完后立刻跑一个最小示例。别只验证版本直接codex init创建一个项目然后codex run看看能不能正常启动。我见过有人装完一周后才发现根本跑不起来因为某个动态库没链接。记录你的安装方式。在~/.zshrc里加一行注释比如# CodeX installed via brew on 2024-03-15。半年后你回来维护时会感谢现在的自己。遇到报错先看日志。CodeX 的日志在~/.codex/logs/下错误信息比终端输出详细十倍。别在终端里瞎猜直接tail -f ~/.codex/logs/error.log看实时输出。如果以上都搞不定直接删掉重装。brew uninstall codex然后brew cleanup再重新安装。有时候是 brew 的缓存坏了重装比排查快得多。最后别被这些报错吓到。CodeX 在 macOS 上的稳定性其实不错大部分问题都是环境配置引起的。装好之后你会发现它比很多同类工具都顺手。下一篇我会讲 CodeX 的初始化配置和第一个项目实战到时候见。
