企业官网建设流程全解析

mac 上跑npm install -g @openai/codex装 Codex CLI 的时候，不少朋友应该都撞过这个场景：命令刚执行没几秒，终端就蹦出一串红色报错，里面最扎眼的那个是npm error code ENOTEMPTY。我头一回看到这个错误码也愣了一下，ENOTEMPTY 平时真不常见，网上一搜，信息还特别零散，有人说清缓存，有人让删目录，还有人干脆建议重装 Node.js——这显然不是最优解。

这篇就围绕「mac + npm + codex + ENOTEMPTY」这条报错链路，把问题背后的安装机制拆开讲清楚，再给一套从环境自检到彻底重装的完整操作流程。顺带把安装成功后 codex 运行时可能碰到的代理报错、deprecated 提示这类后遗症一起解决掉。适合初次在 mac 上安装 codex 的新手，也适合想彻底搞懂 npm 这类诡异报错的开发者。

1. 先把 ENOTEMPTY 的来龙去脉搞清楚

1.1 报错信息拆解：npm 到底在哪个环节翻了车

很多人看到npm error code ENOTEMPTY的第一反应是“没看懂，继续搜”，但拆开看其实并不复杂。ENOTEMPTY 是系统层面的错误码，英文全称是Directory not empty，翻译过来就是“目录非空”。macOS 文件系统在执行某些操作时，如果发现目标目录里面还有文件或子目录，并且操作要求目标目录必须为空，就会返回这个错误。

npm 的安装过程并不是很多人以为的“把包解压到 node_modules 就完事”。npm 在安装一个全局包时，大致会分这么几步：

1. 把包下载到 npm 自己的缓存目录~/.npm/_cacache；
2. 在目标 node_modules 下创建临时目录，常见的是一级.staging目录；
3. 把解压好的文件从缓存中写入.staging临时目录；
4. 最后把临时目录重命名成正式的包目录，比如node_modules/@openai/codex。

问题就出在第 4 步。这个“重命名”操作要求目标位置不能存在同名目录，或者如果存在同名目录，这个目录得是空的。当系统发现node_modules/@openai/codex已经存在，并且里面还有一堆残留文件时，就会直接丢出 ENOTEMPTY。

我实际遇到过的情况是：之前一次安装因为网络抖动被中断，npm 已经把 codex 的部分文件写进了@openai/codex目录，但后续步骤没有完成。第二次重装时，npm 想重新创建这个目录，结果发现它非空，于是直接罢工。

1.2 为什么 macOS 上这个错误尤其容易复现

ENOTEMPTY 并不是 mac 专属，Linux 上也会出现，但 macOS 上有几个特有的“坑”会显著提高触发概率，这里值得单独说一下。

第一，macOS 默认的 APFS 文件系统对大小写不敏感。这意味着OpenAI和openai在绝大多数情况下会被当成同一个目录。npm 在安装@openai/codex时，会同时操作node_modules/@openai这个作用域目录，如果之前曾经用某个包创建过同名但大小写不同的目录，文件系统层面就可能产生冲突。

第二，macOS 的 Spotlight 索引、第三方安全软件实时扫描，会在文件重命名瞬间短暂占用目录句柄。虽然这个概率不高，但在包体积较大、目录层级较深时更容易触发。Codex 这个 CLI 工具本身依赖不少原生模块，文件数量多，重命名耗时相对长，恰好就比普通包更容易踩中这个窗口期。

第三，也是最常见的原因：全局 node_modules 目录的权限混乱。很多 mac 用户安装 Node.js 时用的是 Homebrew，而 Homebrew 安装 Node 的目录要么是/usr/local，要么是/opt/homebrew。如果你之前使用过sudo npm install安装过全局包，那么某些目录的 owner 就变成了 root。后续再用普通用户身份执行 npm 安装时，npm 无法删除或覆盖这些 root 属主的目录，也会在“目录非空”这一步直接报错。

1.3 从日志里找真正原因，不要盲猜

ENOTEMPTY 报错信息本身比较简短，但 npm 通常会附上更详细的上下文。执行安装命令时，如果报错，不要急着关终端，把完整输出多看几行，重点找这几类线索：

• npm error path ...：报错的具体路径，能直接告诉你到底是哪个目录出了问题；
• npm error syscall rename：说明卡在重命名阶段；
• npm error errno -66：-66 是 ENOTEMPTY 在 macOS 上的数字编号；
• npm error dest ...：重命名的目标目录。

如果输出信息不够多，还可以用npm install -g @openai/codex --loglevel verbose重新跑一遍，npm 会打印每一步操作的详细日志，能看到它具体在哪一步、操作哪个路径时失败。

注意：macOS 上看到syscall rename和errno -66这两个信息基本可以锁定是 ENOTEMPTY，不用再怀疑其他原因。

2. 动手修复前，先做一轮环境自检

2.1 确认 Node.js 和 npm 的版本与全局目录

我见过不少人装 codex 报错，排查了半天，最后发现是自己 Node.js 版本太老，npm 的行为和现代版本不一样，导致一系列诡异问题。所以第一步不是清理缓存，而是先确认环境。

在终端依次执行：

node -v npm -v npm config get prefix npm root -g

npm config get prefix会输出 npm 安装全局包的根目录，比如/usr/local或/opt/homebrew。npm root -g则直接给出全局 node_modules 的完整路径，比如/opt/homebrew/lib/node_modules。记住这个路径，后面清理残留目录时会用到。

如果你是用 Homebrew 安装的 Node.js，并且电脑是 Apple Silicon 芯片，全局目录通常在/opt/homebrew/lib/node_modules；如果是 Intel 芯片，则一般在/usr/local/lib/node_modules。如果你用的是官方 pkg 安装包，路径可能是/usr/local/lib/node_modules。这里没有标准答案，一切以你本机npm root -g的输出为准。

2.2 检查全局目录权限：是不是被 sudo 污染过

这一步非常关键，mac 上 ENOTEMPTY 有很多次都是权限问题伪装成目录冲突。执行：

ls -ld "$(npm root -g)" ls -ld "$(npm root -g)/@openai" 2>/dev/null || echo "目录不存在"

如果看到目录 owner 是 root，而你当前登录用户不是 root，那么你普通用户执行 npm install 时，对目录里面的文件没有写权限。npm 尝试清理旧文件时就会失败，表现出来可能就是 ENOTEMPTY，有时候也会变成 EACCES。

最稳妥的解决思路是不要用sudo npm install -g，而是用 nvm 这类 Node 版本管理器，把 Node 安装到用户目录下，全局包也自然落在用户目录，从根上避开权限问题。

# 如果还没有 nvm，可以按 nvm 官方 README 安装 # 安装完成后，node、npm 和全局 node_modules 都会在用户目录下 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

如果你不想切换 Node 版本管理器，也可以简单地把全局目录授权给自己，但这需要你明确知道当前目录的确切路径：

sudo chown -R $(whoami) "$(npm root -g)"

这条命令的意思是把全局 node_modules 目录的所有权从 root 改成当前用户。执行之后，npm 不需要 sudo 也能正常创建和删除目录。

2.3 检查 npm 镜像源配置，避免“源不对”带来的干扰

在 mac 上安装 codex 时，npm 默认从官方源下载，但国内用户为了提速通常会配置镜像源。npm 镜像源配置本身没有问题，但如果配置了老的淘宝源https://registry.npm.taobao.org，在某些情况下会碰到证书过期错误（CERT_HAS_EXPIRED），表现和 ENOTEMPTY 不同，但同样会中断安装。

查看当前源：

npm config get registry

如果输出的是https://registry.npmjs.org/，那说明是官方源。如果输出的是老淘宝源，建议切换到新的 npmmirror 源：

npm config set registry https://registry.npmmirror.com

或者直接编辑~/.npmrc文件，把 registry 那一行改成新地址。改完后重新检查一遍，确认生效即可。

提示：npm 的 registry 配置是全局生效的，改完后所有 npm install 都会走新源。如果之前做过某些包的私有源配置，改动前先看一眼~/.npmrc里的完整内容。

3. 解决 ENOTEMPTY 的完整实操：从清理到重装

3.1 第一步：安全卸载可能存在的 codex 残留

在清理之前，先尝试用 npm 正常卸载一遍 codex。虽然 ENOTEMPTY 报错说明卸载可能也会遇到问题，但值得先试一次，因为如果卸载能成功，后面会省很多事：

npm uninstall -g @openai/codex

如果卸载成功，终端没有任何报错，那么直接跳到 3.4 重新安装。如果卸载过程还是报 ENOTEMPTY，或者提示目录不存在，那么进入下面的手动清理流程。

3.2 第二步：确认并手动删除残留目录

卸载失败时，最直接的办法就是手动删除残留的 codex 目录。先定位目录位置：

npm root -g

假设输出的全局 node_modules 路径是/opt/homebrew/lib/node_modules，那么需要重点检查这几个位置：

1. /opt/homebrew/lib/node_modules/@openai：这是 codex 包的主目录，如果存在且里面有残留文件，直接删掉整个@openai作用域目录。
2. /opt/homebrew/lib/node_modules/codex：有些情况下 npm 会生成不带 scope 的目录，存在也一并删掉。
3. /opt/homebrew/bin/codex：这是 npm 为全局命令创建的软链接，正常情况下指向../lib/node_modules/@openai/codex/bin/codex.js。如果它指向的目标已经不存在或损坏，删掉重装时会自动重建。

删除之前，可以先看看目录里到底有什么：

ls -la "$(npm root -g)/@openai" 2>/dev/null

确认没有其他重要包后，执行删除：

rm -rf "$(npm root -g)/@openai" rm -f "$(npm prefix -g)/bin/codex"

提醒：rm -rf是危险操作，务必确认路径正确再执行。建议先执行npm root -g，复制输出的完整路径，不要凭记忆手打路径。

3.3 第三步：清理 npm 缓存，排除坏缓存干扰

残留目录删干净后，接下来要处理 npm 缓存。ENOTEMPTY 有不少情况是缓存中已经存在解压一半的临时文件，导致后续验证和重命名环节出错。执行：

npm cache clean --force

这条命令会把~/.npm/_cacache下的缓存内容清空。如果觉得--force太暴力，也可以先执行npm cache verify，让 npm 自己检查并清理损坏条目。实测下来，ENOTEMPTY 场景直接clean --force更干脆，省得反复验证浪费时间。

清理完缓存后，还有一层保险操作：删除.staging临时目录。npm 安装中断时，会在全局 node_modules 下留下.staging目录，这个目录有时候不会被后续安装自动复用，反而会干扰重命名操作。

rm -rf "$(npm root -g)/.staging"

3.4 第四步：重新安装 codex 并验证结果

清理完成后，重新执行安装命令：

npm install -g @openai/codex

这次正常情况下应该能顺利装完。如果网络状态不太稳定，可以加--fetch-retries=5增加重试次数，或者使用国内镜像源来提速：

npm install -g @openai/codex --registry https://registry.npmmirror.com

安装完成后，验证一下是否真的装好了：

codex --version which codex

codex --version能输出版本号说明安装成功。which codex则告诉你可执行文件的实际路径，正常情况下是在 npm 全局 bin 目录下，比如/opt/homebrew/bin/codex。

4. 安装成功之后：Codex 初始化和运行时问题处理

4.1 初始化登录：codex login 的前置条件

安装只是第一步，codex 要真正跑起来，还需要登录账号并完成初始化配置。执行：

codex login

这里会打开浏览器，引导你完成账号授权。如果你打算用 API Key 方式，可以执行codex login --api-key并粘贴 Key。无论哪种方式，登录完成后 codex 会把凭证写入~/.codex目录下的配置文件里。

登录完成后，执行codex init会在当前目录生成codex.md之类的配置文件，告诉 codex 这个项目的上下文说明。我建议在项目根目录跑一下codex init，把项目背景简单写进去，后续 codex 在执行任务时对项目结构的理解会更准确。

4.2 那些年 codex 跑不起来的“代理报错”到底是谁的锅

codex 安装成功后，有些用户会在运行时看到类似cc switch local proxy failed while handling codex endpoint /responses的报错。第一次看到这个信息确实容易被吓到，以为 codex 本身出了问题。这里我单独解释一下。

codex CLI 在运行时会读取当前终端环境中的本地代理相关变量，比如HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这些环境变量。如果你的终端里配置了这些变量，但实际对应的本地代理进程没有启动，或者端口号对不上，codex 在切换本地代理连接时就会失败，报错文案里就会出现switch local proxy failed。

排查思路很简单：

env | grep -i proxy

如果没有输出，说明环境变量里没有设置代理，这个报错不太可能是环境变量引起的。如果输出了类似HTTP_PROXY=http://127.0.0.1:7890的内容，那就是有代理配置。此时检查 7890 端口是否有对应进程在监听：

lsof -i :7890

如果端口没有程序监听，那说明代理进程没起，要么启动对应代理工具，要么在当前终端临时清掉这些环境变量再运行 codex：

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY codex

提示：codex 的报错信息有时比较“虚”，switch local proxy failed并不一定代表你的网络有问题，更多时候是本地环境变量与代理端口不匹配。先查环境变量，再查端口监听，基本能定位九成问题。

4.3 安装时出现的 node-domexception deprecated 警告需要处理吗

安装 codex 的过程中，很多人会注意到npm warn deprecated node-domexception@1.0.0这类警告。这里明确说一下：这是 npm 在提醒某个依赖包已经过时，不再推荐使用，但它并不是错误，也不会导致安装失败。

node-domexception 是较早用于在 Node.js 中模拟 DOMException 的小工具包，随着 Node.js 自带实现逐渐完善，这个包被标记为 deprecated。codex 的依赖链里某个老包可能还在引用它，npm 只是顺便提醒一句。这种情况不需要做任何处理，忽略即可。如果你有强迫症，非要让安装过程完全干净，那只能等上游依赖更新替换掉这个包，普通用户层面没有可操作空间。

5. 常见问题与排查技巧实录

5.1 ENOTEMPTY 及其他相关报错速查表

把我在 mac 上安装 codex 前后遇到过的各种报错整理成一张表，方便后续遇到问题时直接对照：

5.2 mac 上避免再踩 ENOTEMPTY 的 3 个习惯

第一次解决 ENOTEMPTY 之后，很长一段时间我都没再遇到过同类问题，核心原因是养成了几个安装全局包的习惯。这里分享一下。

第一个习惯：尽量不用 sudo 安装全局包。mac 上很多权限类 npm 报错都是从一次sudo npm install开始的。sudo 装完的目录归 root 所有，后续普通用户安装升级都会受限。推荐的做法是用 nvm 安装 Node.js，全局包默认装在用户目录，比如~/.nvm/versions/node/v22.x.x/lib/node_modules，这样不会有权限冲突。

第二个习惯：安装过程中不随意中断。npm install 虽然看起来进度条走得很快，但内部在解压、重命名时如果被 Ctrl+C 打断，很容易留下一堆半成品目录。如果网速慢导致安装没反应，宁可多等一会，也别频繁中断重试。

第三个习惯：定期清理发霉的缓存。npm cache clean --force不是每天都要跑，但在你发现某个包装不上去、报错又比较奇怪时，先清一次缓存再重装，能省掉很多排查时间。

5.3 安装完成后 codex 使用中的几个小技巧

codex 装好之后，有几个小细节可以让使用过程顺畅很多。

一是终端里配置好 PATH。如果你用的是 nvm，那么 Node 的 bin 目录默认已经在 PATH 里。如果你用其他方式安装的 Node，并且codex命令提示找不到，执行echo $PATH看看是否包含npm prefix -g里输出的 bin 路径。如果不包含，在~/.zshrc或~/.bash_profile里加上：

export PATH="$(npm prefix -g)/bin:$PATH"

然后source ~/.zshrc让配置生效。

二是如果 codex 启动后响应异常，先看~/.codex目录下的日志。codex 会把运行日志写在~/.codex/log或类似位置，具体路径可以执行codex --debug启动一次，它会打印更详细的日志路径。排查实际问题时，日志里的信息永远比终端报错有用。

三是如果你不想每次都在项目目录重新配置上下文，可以在~/.codex下维护一个全局配置，把常用的工作习惯写进去，这样 codex 每次运行时都能读到你的偏好设置，减少重复沟通成本。

写在最后

ENOTEMPTY 这类报错，mac 上之所以反复出现，本质上就是「目录残留 + 权限混乱 + npm 重命名机制」三件事凑在一起。遇到它别慌，也不要一上来就重装 Node.js，先定位残留目录，再检查权限，最后清一遍缓存重装，九成情况都能解决。我个人在实际操作中的体会是：mac 上跑 npm 全局安装，尽量用 nvm 管理环境，从源头避开权限问题，能省掉后面一大堆奇奇怪怪的坑。codex 本身是个很好用的命令行编程工具，装好之后的体验完全值得你在安装上多花几分钟。