1. 为什么 Windows 上跑 Codex 总在第一步就卡住
如果你在 Windows 上折腾过 Codex，大概率经历过这样的场景：照着某篇教程敲完命令，终端里蹦出一行红字，然后整个人就愣在那里。搜了半天，发现别人用 Mac 或者 Linux 一路顺畅，自己却在 PowerShell 的执行策略、Node.js 的路径、npm 的镜像源之间反复横跳。这不是你的问题，而是 Windows 的生态环境和 Codex 这类工具默认假设的 Unix 环境之间存在天然的摩擦。
Codex 本质上是一个依赖 Node.js 运行时环境的命令行工具，它的安装链路是：Node.js 提供运行时，npm 负责包管理，Codex 作为 npm 包被拉取到本地，然后通过命令行调用。这条链路上任何一个环节出问题，都会导致安装失败或者运行异常。而 Windows 恰恰在这条链路上埋了好几个坑：PowerShell 默认禁止运行脚本、npm 全局包的路径可能不在系统 PATH 里、国内网络环境下默认源拉取速度极慢甚至超时、Node.js 版本和 Codex 要求的版本不匹配等等。
这篇内容面向的是在 Windows 上从零开始配置 Codex 的开发者，不管你之前有没有用过 Node.js 生态的工具，只要跟着走，就能把环境搭起来。我会把每个步骤背后的原因讲清楚，同时把我在实际配置过程中踩过的坑和验证过的解决方案一并分享出来。整个流程大致分为四个阶段：Node.js 环境的安装与验证、npm 的配置与镜像源优化、Codex 的安装与初始化、以及常见报错的排查与修复。每个阶段都有一些容易被忽略的细节，而这些细节往往就是决定成败的关键。
2. Node.js 安装：版本选择与安装方式的取舍
2.1 LTS 版本和 Current 版本到底选哪个
打开 Node.js 官网，首页会给你两个下载选项：LTS 和 Current。很多人随手就点了 Current，觉得版本越新越好。但在 Codex 这个场景下，我强烈建议选 LTS 版本。原因很简单：Codex 依赖的一些底层 npm 包可能还没有适配最新的 Node.js 版本，用 Current 版本很容易遇到一些莫名其妙的兼容性问题，比如某个原生模块编译失败、某个 API 行为变更导致工具崩溃。
LTS 的全称是 Long Term Support，也就是长期支持版本。Node.js 官方会对 LTS 版本提供大约 30 个月的安全更新和维护，而 Current 版本的生命周期只有几个月，之后就会变成新的 LTS 或者被废弃。对于开发工具链来说，稳定性远比新特性重要。截至我写这篇内容的时候，Node.js 的 LTS 版本已经更新到了 20.x 系列，这个版本在 Windows 上的兼容性已经非常成熟。
还有一个细节需要注意：Node.js 的版本号是偶数的是 LTS，奇数的是 Current。比如 18.x、20.x、22.x 是 LTS，而 19.x、21.x、23.x 是 Current。你在下载页面看到版本号的时候，可以快速判断一下。
2.2 安装包安装还是包管理器安装
Windows 上安装 Node.js 有两种主流方式：直接下载官网的 .msi 安装包，或者通过 winget、chocolatey、scoop 这类包管理器安装。两种方式各有优劣，我分别说一下。
直接下载 .msi 安装包是最省心的方式。双击运行，一路 Next，安装程序会自动帮你配置好环境变量，包括 Node.js 和 npm 的路径。安装完成后打开一个新的终端窗口，输入node -v和npm -v，如果能正常输出版本号，说明安装成功。这种方式的好处是简单直接，不需要额外安装任何东西。缺点是后续升级 Node.js 版本的时候需要手动下载新版本的安装包重新安装。
通过包管理器安装的好处是升级方便，一条命令就能切换版本。比如用 winget 的话，winget install OpenJS.NodeJS.LTS就能装好。但包管理器本身可能需要额外配置，而且有些包管理器安装的 Node.js 路径可能和系统默认路径不一致，导致后续 npm 全局包找不到。如果你对 Windows 的包管理器不熟悉，我建议还是用 .msi 安装包，少一层抽象就少一个出问题的环节。
注意：不管你用哪种方式安装，安装完成后一定要关闭所有已经打开的终端窗口，重新开一个新的。因为环境变量的更新只对新开的终端生效，旧终端里还是用的旧环境变量。
2.3 安装完成后的验证清单
安装完 Node.js 之后，不要急着装 Codex，先花两分钟做几个验证。打开 PowerShell 或者 CMD，依次执行以下命令：
node -v npm -v where node where npm前两条命令分别输出 Node.js 和 npm 的版本号。如果输出了版本号，说明安装基本没问题。如果提示"不是内部或外部命令"，说明环境变量没有配置好，需要手动检查。
后两条命令where node和where npm在 PowerShell 里可能不生效，因为where是 CMD 的命令。在 PowerShell 里应该用Get-Command node和Get-Command npm。这两条命令会告诉你 node 和 npm 的可执行文件到底在哪个路径下。这个信息很重要，因为后面配置 npm 全局包路径的时候会用到。
还有一个容易忽略的点：检查 npm 的全局包路径是否在系统 PATH 里。执行npm config get prefix，这个命令会输出 npm 全局包的安装路径。在 Windows 上，默认路径通常是C:\Users\你的用户名\AppData\Roaming\npm。你需要确认这个路径已经被添加到了系统的 PATH 环境变量中。如果没有添加，后面安装的 Codex 命令会找不到。
3. npm 配置：镜像源、全局路径与 PowerShell 执行策略
3.1 国内网络环境下必须换镜像源
npm 默认的包仓库地址在国外，国内访问的速度非常不稳定。有时候能跑到几百 KB/s，有时候直接超时。安装 Codex 这种依赖树比较深的工具时，如果中途某个包下载失败，整个安装就会中断，而且 npm 的报错信息往往不够明确，你很难判断到底是哪个包出了问题。
换国内镜像源是最直接的解决方案。目前比较稳定的国内 npm 镜像源有淘宝镜像（npmmirror.com）和腾讯云镜像。我一般用淘宝镜像，更新频率比较高，覆盖的包也比较全。切换命令如下：
npm config set registry https://registry.npmmirror.com执行完之后可以用npm config get registry确认一下是否设置成功。如果输出的是你设置的镜像源地址，说明配置生效了。
如果你只想临时用一次镜像源，不想改全局配置，可以在安装命令后面加--registry参数：
npm install -g codex --registry https://registry.npmmirror.com这种方式适合你只想装一个包、不想影响其他项目的情况。但对于 Codex 这种需要长期使用的工具，我还是建议直接改全局配置，省得每次都要加参数。
3.2 npm 全局包路径的坑
Windows 上 npm 全局包的默认安装路径是C:\Users\你的用户名\AppData\Roaming\npm。这个路径默认会被添加到系统 PATH 里，但有时候会因为各种原因丢失，比如你装了其他工具修改了 PATH，或者 Node.js 安装程序没有正确配置。
验证方法很简单：执行npm config get prefix拿到路径，然后检查这个路径是否在 PATH 环境变量里。在 PowerShell 里可以用$env:Path -split ';'列出所有 PATH 路径，然后肉眼找一下。如果不在，需要手动添加。
添加的方法：打开"系统属性" -> "高级" -> "环境变量"，在用户变量或系统变量的 Path 里新增一条，填入 npm 的全局包路径。添加完成后记得重启终端。
还有一个更隐蔽的问题：如果你之前装过其他版本的 Node.js，或者用过 nvm-windows 这类版本管理工具，npm 的全局包路径可能会指向一个已经不存在的位置。这种情况下，即使你装了 Codex，命令行里也找不到codex命令。解决办法是执行npm config set prefix "C:\Users\你的用户名\AppData\Roaming\npm"把路径重置为默认值，然后重新安装 Codex。
3.3 PowerShell 执行策略：那个让人抓狂的红色报错
如果你在 PowerShell 里执行 npm 命令时看到这样的报错：
npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。这不是 npm 的问题，而是 PowerShell 的执行策略（Execution Policy）在作祟。PowerShell 默认的执行策略是 Restricted，也就是禁止运行任何脚本文件。而 npm 在 Windows 上会生成一个npm.ps1脚本文件，PowerShell 尝试执行这个脚本时就被拦截了。
解决办法是修改 PowerShell 的执行策略。以管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy RemoteSignedRemoteSigned策略的含义是：本地创建的脚本可以运行，从网络下载的脚本需要数字签名才能运行。这个策略在安全性和可用性之间取得了比较好的平衡，也是微软推荐开发者使用的策略。
执行完命令后，PowerShell 会提示你确认是否修改，输入Y回车即可。修改完成后，关闭当前 PowerShell 窗口，重新打开一个，再执行 npm 命令就不会报错了。
注意：如果你用的是 PowerShell 7（也就是 pwsh），执行策略的修改方式是一样的。但如果你用的是 CMD 或者 Git Bash，就不会遇到这个问题，因为 CMD 和 Bash 不依赖 PowerShell 的执行策略。
如果你不想修改全局的执行策略，也可以只针对当前用户修改：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这样只影响当前用户，不影响系统上的其他用户。对于个人开发机来说，这种方式更稳妥。
4. Codex 安装与初始化：从 npm install 到跑通第一条命令
4.1 安装命令与版本选择
环境准备好之后，安装 Codex 本身其实就一条命令：
npm install -g codex-g参数表示全局安装，这样你可以在任何目录下直接使用codex命令。如果不加-g，Codex 只会安装在当前项目的node_modules目录下，只能通过npx codex或者./node_modules/.bin/codex来调用。
安装过程中，npm 会从你配置的镜像源拉取 Codex 及其所有依赖包。如果网络状况良好，通常一两分钟就能装完。如果卡在某个包上不动，可能是镜像源的问题，可以尝试换一个镜像源，或者用npm cache clean --force清理缓存后重试。
安装完成后，执行codex --version验证一下。如果能正常输出版本号，说明安装成功。如果提示"不是内部或外部命令"，说明 npm 全局包路径没有正确添加到 PATH 里，回到上一节检查一下。
4.2 初始化配置与 API 接入
Codex 安装完成后，第一次运行通常需要做一些初始化配置。具体需要配置什么取决于你使用的 Codex 版本和接入的服务。一般来说，你需要配置 API 密钥或者服务端点。
配置的方式通常有两种：一种是通过命令行交互式配置，运行codex init或者codex config之类的命令，按照提示一步步输入；另一种是手动编辑配置文件，配置文件通常位于用户目录下的.codex文件夹里。
如果你使用的是需要 API 密钥的服务，配置的时候注意不要把密钥直接写在命令行里，因为命令行历史会被记录。更好的做法是写到配置文件里，或者通过环境变量传入。在 Windows 上设置环境变量的命令是：
setx CODEX_API_KEY "你的密钥"setx命令会永久设置环境变量，设置完成后需要重新打开终端才能生效。如果只想在当前终端会话中临时设置，用$env:CODEX_API_KEY="你的密钥"（PowerShell）或者set CODEX_API_KEY=你的密钥（CMD）。
4.3 验证安装是否真正可用
很多人装完 Codex 之后，看到codex --version能输出版本号就以为万事大吉了。但实际上，版本号能输出只说明可执行文件在 PATH 里能找到，并不代表 Codex 能正常工作。真正的验证应该是跑一个实际的任务。
你可以创建一个简单的测试文件，然后让 Codex 对它做一些操作。比如创建一个test.js文件，内容随便写几行代码，然后运行codex相关的命令看看能不能正常处理。如果 Codex 能正常读取文件、生成输出，说明整个链路是通的。
如果运行时报错，常见的错误类型包括：API 密钥无效或过期、网络连接超时、配置文件格式错误、依赖包版本不兼容等。根据报错信息逐一排查，大部分问题都能解决。
5. 那些让你怀疑人生的报错：逐个击破
5.1 "npm.ps1 无法加载"的三种触发场景
这个报错我在不同机器上遇到过好几次，触发场景各不相同。第一种是全新安装 Node.js 后第一次在 PowerShell 里执行 npm 命令，这是最典型的情况，解决办法就是前面说的修改执行策略。第二种是你之前修改过执行策略，但后来装了某个安全软件或者系统更新把策略重置了，这种情况需要重新执行Set-ExecutionPolicy RemoteSigned。第三种是你用的不是管理员权限的 PowerShell，而执行策略是在系统级别设置的，当前用户没有权限覆盖，这种情况下需要用管理员权限重新设置，或者改用-Scope CurrentUser参数。
还有一种比较少见的情况：你的 PowerShell 配置文件（profile.ps1）里有语法错误，导致每次启动 PowerShell 都会报错，进而影响 npm 脚本的执行。这种情况下需要检查$PROFILE路径下的配置文件，把有问题的行注释掉。
5.2 安装过程中卡住或超时
npm 安装 Codex 时卡住不动，最常见的原因是网络问题。即使你配置了国内镜像源，某些特定的包可能还是从默认源拉取，或者镜像源本身出现了临时故障。遇到这种情况，可以按以下步骤排查：
首先，用npm config get registry确认镜像源配置是否正确。如果输出的是https://registry.npmjs.org/，说明镜像源没生效，需要重新配置。
其次，尝试用npm install -g codex --verbose查看详细的安装日志。--verbose参数会输出每一步的详细信息，你能看到到底卡在哪个包上。
如果确认是某个包下载超时，可以尝试单独安装那个包，或者换一个镜像源。有时候淘宝镜像对某些冷门包的同步不及时，换成腾讯云镜像或者华为云镜像就能解决。
另外，npm 的缓存有时候也会导致问题。执行npm cache clean --force清理缓存，然后重新安装。这个操作会删除所有已下载的包缓存，下次安装时需要重新下载，但能解决很多莫名其妙的安装失败问题。
5.3 Node.js 版本不兼容导致的报错
Codex 对 Node.js 版本有最低要求，如果你用的版本太老，安装时可能会报错，提示某个包需要更高的 Node.js 版本。报错信息通常长这样：
error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错的意思是某个依赖包要求 Node.js 版本至少是 24.x，但你当前安装的版本低于这个要求。解决办法就是升级 Node.js 到 LTS 版本。去官网下载最新的 LTS 安装包，覆盖安装即可。覆盖安装不会影响你已经安装的 npm 全局包，但保险起见，升级完成后可以执行npm update -g更新一下全局包。
如果你不想升级 Node.js，也可以尝试安装 Codex 的旧版本，旧版本可能对 Node.js 版本要求更低。用npm install -g codex@版本号可以安装指定版本。但我不推荐这种做法，因为旧版本可能存在已知的安全漏洞或者功能缺陷。
5.4 全局包安装成功但命令找不到
这种情况通常是因为 npm 全局包路径没有添加到 PATH 里。前面已经讲过怎么检查和添加，这里补充一个快速验证的方法：执行npm list -g --depth=0列出所有全局安装的包。如果 Codex 在列表里，说明安装成功了，问题出在 PATH 配置上。如果不在列表里，说明安装过程出了问题，需要重新安装。
还有一种可能是你用了 nvm-windows 管理 Node.js 版本，切换版本后全局包路径变了。nvm-windows 的一个特点是，每个 Node.js 版本有独立的全局包目录。你在 A 版本下安装的 Codex，切换到 B 版本后就找不到了。解决办法是在当前使用的 Node.js 版本下重新安装 Codex，或者用nvm use 版本号切换回安装 Codex 时用的那个版本。
6. 让 Codex 用起来更顺手的几个配置技巧
6.1 配置 npm 缓存和超时时间
npm 默认的缓存策略和超时时间在 Windows 上可能不太理想。你可以通过以下配置优化：
npm config set cache "D:\npm-cache" --global npm config set fetch-timeout 60000 npm config set fetch-retry-mintimeout 10000 npm config set fetch-retry-maxtimeout 60000把缓存目录设置到一个空间比较大的盘符，避免 C 盘空间不足。把超时时间从默认的 30 秒延长到 60 秒，给网络波动留出更多余量。重试超时时间设置成 10 秒到 60 秒之间，这样在网络不稳定的情况下 npm 会自动重试，而不是直接失败。
6.2 用 npx 代替全局安装
如果你不想在系统里全局安装 Codex，或者需要在多个版本之间切换，可以用 npx 来运行：
npx codex@latestnpx 会自动下载最新版本的 Codex 并运行，不会污染全局环境。缺点是每次运行都需要检查更新，启动速度会慢一些。适合偶尔使用或者测试新版本的场景。
6.3 在 VSCode 中集成 Codex
如果你平时用 VSCode 开发，可以把 Codex 集成到 VSCode 的终端里，这样不用来回切换窗口。VSCode 的集成终端默认使用 PowerShell，所以前面说的执行策略问题同样适用。你可以在 VSCode 的设置里把默认终端改成 CMD 或者 Git Bash，避免 PowerShell 的执行策略问题。
另外，VSCode 有一些 Codex 相关的插件，可以在编辑器内直接调用 Codex 的功能。安装插件后，按照插件的说明配置 API 密钥和服务端点即可。插件的好处是可以在编辑器内直接看到 Codex 的输出，不用切换到终端窗口。
6.4 定期更新 Codex 和 Node.js
Codex 和 Node.js 都在持续更新，新版本通常会修复一些已知问题、提升性能、增加新功能。建议每隔一两个月检查一下更新。更新 Codex 的命令是：
npm update -g codex更新 Node.js 的话，去官网下载最新的 LTS 安装包覆盖安装即可。更新之前建议先记录一下当前使用的版本号，万一新版本有问题可以回退。
7. 我在多次配置中积累的几个经验
配置 Codex 这件事，说难不难，说简单也不简单。第一次配置的时候我花了将近两个小时，各种报错轮番出现，一度怀疑是不是自己的电脑有问题。后来帮同事配置了几次，慢慢总结出一些规律。
最重要的一条经验是：先把 Node.js 和 npm 的环境彻底搞定，再动 Codex。很多人一上来就npm install -g codex，结果报了一堆错，然后开始怀疑是 Codex 的问题。实际上大部分报错都跟 Codex 本身无关，而是 Node.js 环境没配好。花十分钟把 Node.js 版本、npm 镜像源、全局包路径、PowerShell 执行策略这四项检查一遍，能省掉后面大量的排查时间。
第二条经验是：遇到报错先看报错信息的第一行和最后一行。npm 的报错信息通常很长，中间一大段是调用栈，真正有用的信息在第一行（错误类型）和最后一行（具体原因）。比如npm ERR! code EACCES说明是权限问题，npm ERR! code ETIMEDOUT说明是网络超时，npm ERR! code ENOENT说明是文件找不到。根据错误码快速定位问题类型，比逐行读报错信息效率高得多。
第三条经验是：保持终端环境干净。Windows 上的环境变量很容易被各种软件修改，装一个软件可能就往 PATH 里塞一条路径，时间长了 PATH 会变得很长很乱。建议定期检查一下 PATH 环境变量，把不用的路径清理掉。另外，如果你同时装了多个版本的 Node.js，建议用 nvm-windows 统一管理，避免版本冲突。
最后分享一个快速排查环境问题的小技巧：创建一个check-env.bat文件，把常用的检查命令写进去，每次配置新机器的时候直接运行这个脚本，几秒钟就能看完所有关键信息。脚本内容大概是这样：
@echo off echo === Node.js 版本 === node -v echo === npm 版本 === npm -v echo === npm 镜像源 === npm config get registry echo === npm 全局包路径 === npm config get prefix echo === 全局包列表 === npm list -g --depth=0 echo === PATH 中的 Node.js 相关路径 === echo %PATH% | findstr /i "nodejs npm" pause把这个脚本放在桌面或者常用目录下，每次遇到环境问题先跑一遍，大部分问题都能快速定位。这个习惯帮我省了很多时间，也推荐给你。
