1. 为什么 Windows 上跑 Codex 总在第一步就卡住如果你最近在 Windows 上折腾 Codex大概率经历过这样的场景照着某篇教程敲下第一条命令终端直接甩给你一句npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本然后整个人就愣在那里。这不是你操作错了而是 Windows 的 PowerShell 默认执行策略在拦路。很多人第一次接触 Codex 时把注意力全放在怎么接入模型怎么配 API上结果连环境都没跑通后面全是空谈。Codex 本质上是一个跑在本地终端里的 AI 编程助手它依赖 Node.js 运行时和 npm 包管理器来安装和启动。在 Windows 上这套工具链的安装路径、权限模型、终端环境和 Linux/macOS 有本质区别所以网上大量基于 macOS 的教程直接照搬过来会处处碰壁。这篇内容面向的是完全没有 Node.js 基础、或者装过但被各种报错劝退的 Windows 用户我会从零开始把 Node.js 安装、npm 配置、Codex 安装、VSCode 联动这几件事讲透每一步都告诉你为什么这么做以及踩坑了怎么救。需要先明确一点Codex 的安装和使用本身不复杂复杂的是 Windows 这套环境的历史包袱。PowerShell 执行策略、PATH 环境变量、npm 全局目录权限、镜像源配置这四个东西任何一个出问题都会让你卡住。我见过太多人在这四步里反复重装 Node.js 五六次其实问题根本不在 Node.js 本身。下面我按真实排查顺序展开你可以对照自己的报错直接跳到对应章节。2. Node.js 安装版本选择与安装方式的取舍2.1 LTS 版本才是正解别追最新打开 Node.js 官网你会看到两个下载按钮LTS 和 Current。LTS 是长期支持版Current 是最新特性版。很多人手贱点了 Current结果装完发现某些 npm 包编译报错或者 Codex 依赖的某个库不兼容。我实测下来Codex 这类工具链对 Node.js 版本的要求是稳定优先直接选 LTS 就行。截至我写这篇内容时LTS 主线在 20.x 和 22.x 之间选 20.x 或更高的 LTS 都可以别去碰奇数版本号比如 21、23那些是过渡版本生命周期短。还有一个热词里出现的报错error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这就是典型的版本号写错或者镜像源还没同步导致的。你如果手动指定了一个不存在的版本号npm 或 nvm 就会报这个。解决办法很简单去官网确认当前真实存在的 LTS 版本号别凭记忆瞎填。2.2 安装包安装 vs 包管理器安装Windows 上装 Node.js 有两条路一是直接下载.msi安装包双击安装二是用nvm-windows或fnm这类版本管理工具。我的建议是如果你只用一个版本直接.msi最省事如果你需要多个项目切换不同 Node 版本那就上nvm-windows。.msi安装包的好处是它会自动帮你配好 PATH 环境变量装完在终端敲node -v和npm -v就能看到版本号。坏处是它默认装到C:\Program Files\nodejs\这个路径带空格某些老工具处理路径时容易出问题而且 Program Files 目录需要管理员权限才能写入这直接导致了后面 npm 全局安装的权限坑。用nvm-windows的话Node 会装到用户目录下不需要管理员权限切换版本也方便。但 nvm-windows 本身有个坑安装前必须先卸载已有的 Node.js否则 PATH 会冲突。我建议新手先用.msi把流程跑通等熟悉了再考虑 nvm。2.3 安装时必须勾选的那几个选项.msi安装向导里有一个关键页面默认可能没勾选Add to PATH。你一定要确认这一项是选中的否则装完终端里根本找不到 node 命令。另外还有一个选项是Automatically install the necessary tools这个会顺带装 Python 和 Visual Studio Build Tools体积很大几个 G如果你只是跑 Codex 这种纯 JS 工具可以不勾省时间。但如果你后续要装需要编译的原生模块比如某些数据库驱动那就得勾上或者事后单独装。装完之后务必关掉所有已打开的终端窗口再重新打开。PATH 环境变量的更新不会自动同步到已经运行的终端进程里这是无数人明明装了却提示找不到命令的根本原因。我见过有人装完 Node 后在原来的 PowerShell 里敲node -v报错重启终端就好了白白折腾半小时。3. npm 报错禁止运行脚本的完整排查链路3.1 这个报错的本质是什么npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本——这句话的关键词是禁止运行脚本。Windows PowerShell 有一个叫执行策略Execution Policy的安全机制默认是Restricted意思是任何.ps1脚本都不许跑。npm 在 Windows 上是通过一个npm.ps1脚本包装的所以直接被拦下了。这不是 npm 的问题也不是 Node.js 的问题纯粹是 PowerShell 的安全策略。你在 CMD命令提示符里跑同样的命令可能就没事因为 CMD 不走 PowerShell 的执行策略。但 VSCode 默认终端是 PowerShell所以这个坑几乎人人都会踩。3.2 查看当前执行策略先别急着改先看看当前是什么状态。打开 PowerShell敲Get-ExecutionPolicy如果返回Restricted那就是它没跑了。如果返回RemoteSigned或Unrestricted那你的报错可能是别的原因比如路径里真的没有 npm.ps1 文件。3.3 改成 RemoteSigned 而不是 Unrestricted网上有些教程让你直接设成Unrestricted我不推荐。Unrestricted意味着任何脚本都能跑包括从网上下载的恶意脚本。更稳妥的做法是设成RemoteSigned本地写的脚本可以跑从网络下载的脚本必须有数字签名才能跑。对日常开发来说这个级别足够了。改的时候要注意作用域。执行策略有多个作用域Process当前会话、CurrentUser当前用户、LocalMachine整台机器。我建议用CurrentUser这样不需要管理员权限也不会影响系统其他用户Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行后会提示你确认输入Y回车。然后再敲一次Get-ExecutionPolicy -Scope CurrentUser确认改成功了。注意如果你在公司的电脑上操作组策略可能锁定了执行策略你改了也会被强制还原。这种情况下要么找 IT 开权限要么改用 CMD 作为终端或者用 Git Bash。3.4 改完还是报错怎么办如果执行策略改了还是报同样的错按这个顺序排查第一确认报错路径里的npm.ps1文件真实存在。去C:\Program Files\nodejs\目录下看一眼有没有npm.ps1、npm.cmd、npm这三个文件。如果只有npm.cmd没有npm.ps1说明你的 Node 安装不完整重装。第二确认你改的是当前用户作用域而不是改了 Process 作用域关掉终端就失效了。第三检查是不是有多个 Node.js 安装路径冲突。热词里出现了D:\Program Files\nodejs\npm.ps1这个路径说明有人把 Node 装到了 D 盘。如果你之前装过一次到 C 盘又装了一次到 D 盘PATH 里可能两个都有终端找到的是旧的那个。用where.exe node和where.exe npm看看实际调用的是哪个路径。第四如果用的是 VSCode改完执行策略后要完全重启 VSCode不是关掉终端面板是退出整个 VSCode 进程再打开。4. npm 镜像源与全局目录的配置细节4.1 为什么必须换国内镜像源npm 默认的 registry 在国外国内访问经常超时或者慢到无法忍受。装 Codex 这种依赖树比较深的包时一个超时就会导致整个安装失败然后你重试又失败非常折磨。换成国内镜像源是最直接的提速手段。目前常用的镜像源有几个我一般用淘宝源现在叫 npmmirrornpm config set registry https://registry.npmmirror.com设置完用npm config get registry确认一下。想换回官方源就把地址改成https://registry.npmjs.org。这里有个细节有些公司内网有自己的私有 registry如果你在公司环境里别随便改全局 registry否则可能连不上私有包。这种情况下可以用--registry参数临时指定或者用.npmrc文件做项目级配置。4.2 全局安装目录的权限坑前面提到.msi默认把 Node 装到C:\Program Files\nodejs\npm 的全局包默认也装在这个目录下的node_modules里。问题是 Program Files 需要管理员权限才能写入所以你跑npm install -g的时候会报EACCES或EPERM权限错误。解决方案有两个。方案一是每次全局安装都用管理员身份打开终端但这很烦。方案二是把 npm 的全局目录改到用户目录下npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm改完之后要把这个新路径加到 PATH 环境变量里否则全局安装的命令行工具找不到。具体操作Win 键搜索环境变量打开编辑系统环境变量在用户变量里找到 Path新增一条C:\Users\你的用户名\AppData\Roaming\npm。改完 PATH 同样要重启终端才生效。这一步做完以后npm install -g就不需要管理员权限了。4.3 缓存清理与卸载全局包npm 用久了缓存会堆积有时候安装报错其实是缓存损坏导致的。清理命令npm cache clean --force卸载全局包用npm uninstall -g 包名如果你忘了包名用npm list -g --depth0列出所有全局包。热词里有人搜npm卸载全局包多半是装错了想删掉重来。注意卸载全局包同样受权限影响如果之前是用管理员权限装的卸载时也得用管理员权限。5. Codex 安装与首次启动的实操步骤5.1 安装前的环境自检在装 Codex 之前先跑一遍自检确认基础环境没问题node -v npm -v npm config get registry三条命令分别返回 Node 版本号、npm 版本号、镜像源地址就说明环境 OK。如果任何一条报错回到前面章节解决别硬着头皮往下装。5.2 安装 CodexCodex 通过 npm 全局安装。命令是npm install -g openai/codex如果你看到进度条卡住不动多半是镜像源没生效或者网络问题CtrlC 中断后重新确认 registry 配置。安装完成后敲codex --version看是否正常输出版本号。如果提示命令未找到说明全局目录没加到 PATH回到 4.2 节检查。安装过程中如果出现cc switch local proxy failed while handling codex endpoint /responses这类报错这通常和本地代理配置有关。检查一下你的系统代理设置或者 npm 的 proxy 配置npm config get proxy npm config get https-proxy如果返回了非空值但你并不需要代理用npm config delete proxy和npm config delete https-proxy删掉。5.3 首次启动与配置安装完成后在终端里直接敲codex启动。首次启动会引导你做一些基础配置比如选择模型、填入 API 凭证等。这一步的具体选项会随版本变化我不在这里写死你按屏幕提示走就行。有一个经验首次启动建议在一个空目录里进行别在大型项目根目录直接启动因为 Codex 会扫描当前目录的文件作为上下文目录太大启动会慢而且可能读到你不希望它读的文件。5.4 接入第三方模型的注意事项热词里出现了codex接入deepseek说明很多人想用 Codex 接非默认的模型。这类操作的核心是配置 API 端点和密钥。你需要拿到目标模型服务商提供的 API 地址和 key然后在 Codex 的配置里填进去。具体配置文件的路径和字段名随版本不同建议直接看 Codex 官方文档的配置章节。这里要提醒的是接入第三方模型时注意 API 地址的格式有些服务商要求带/v1后缀有些不带填错了会报 404 或连接失败。另外密钥不要硬编码在会提交到 git 的文件里用环境变量管理。6. VSCode 联动让 Codex 在编辑器里跑起来6.1 VSCode 安装与中文汉化VSCode 官网下载 Windows 版双击安装。安装时建议勾选添加到 PATH和将通过 Code 打开操作添加到资源管理器目录上下文菜单后者能让你在文件夹右键直接打开 VSCode非常方便。汉化很简单打开 VSCode按CtrlShiftX打开扩展面板搜索Chinese安装官方中文语言包重启即可。热词里vscode汉化搜索量很高但这一步真的就三十秒的事。6.2 在 VSCode 终端里使用 CodexVSCode 内置终端默认是 PowerShell所以前面讲的执行策略问题在这里同样会遇到。如果你已经按第 3 章改好了执行策略VSCode 终端里直接敲codex就能用。如果 VSCode 终端里报错但外部 PowerShell 正常检查 VSCode 的终端配置CtrlShiftP打开命令面板输入Terminal: Select Default Profile确认选的是 PowerShell 而不是别的。有时候 VSCode 会默认用旧版 PowerShell 或者 WSL 终端导致环境不一致。6.3 常用插件搭配跑 Codex 的同时我建议装几个辅助插件提升体验。一个是Error Lens它会把报错直接显示在代码行旁边不用你翻终端。另一个是GitLens方便看代码改动历史。如果你写 Python 或 C对应的语言插件也装上热词里vscode配置c/c环境就是这个需求。插件不是越多越好装太多会拖慢启动速度。我一般只留真正每天用的那几个。7. 那些让人抓狂的报错与对应解法7.1 端口占用与关闭端口开发过程中经常遇到端口被占用比如 Codex 或某个本地服务启动时提示EADDRINUSE。Windows 上查端口占用的命令netstat -ano | findstr :端口号拿到最后一列的 PID然后taskkill /PID 进程号 /F热词里windows关闭端口号就是这个操作。注意/F是强制结束确认那个进程确实该杀再执行别把系统关键进程干掉了。7.2 权限相关的启动报错热词里有一条error: start the windows daemon from a non-elevated terminal; shared clients这说的是某个守护进程要求从非管理员终端启动。这类报错的通用解法是不要用管理员身份打开终端用普通用户终端启动。很多工具出于安全考虑明确拒绝在提权环境下运行。7.3 环境变量改了不生效这是最高频的问题。记住一个原则环境变量的修改只对修改之后新启动的进程生效。你改了 PATH当前开着的终端、VSCode、CMD 全都不认必须全部关掉重开。如果重启后还不生效用echo %PATH%CMD或$env:PATHPowerShell打印当前 PATH看看你加的路径到底在不在里面。不在的话说明你改错了地方比如改到了系统变量但实际用的是用户变量或者反过来。7.4 安装包下载失败的兜底方案如果 npm 安装某个包反复失败可以试试清缓存后重装或者临时切换到官方源再切回来。极端情况下可以手动下载包的 tarball 然后本地安装但这属于最后手段一般用不上。8. 我踩过的坑和几条实在建议第一个坑是装完不重启终端。我早期至少有三四次以为是安装失败其实只是终端没刷新 PATH。现在我的习惯是任何环境变量相关的操作做完第一件事就是关掉所有终端重开。第二个坑是多个 Node 版本共存导致混乱。我一度同时装了.msi版和 nvm 版结果where node出来两条路径终端调用的是哪个全看 PATH 顺序非常玄学。后来我统一用 nvm 管理把.msi版彻底卸载干净问题就没了。如果你也遇到命令行为诡异的情况先跑where node和where npm看看是不是有多份。第三个坑是镜像源和代理打架。我有次配了国内镜像源又开着系统代理结果 npm 请求走代理绕了一圈反而更慢还时不时超时。后来把 npm 的 proxy 配置清空只留镜像源速度立刻正常。这两个东西别同时开。最后一个建议把常用的配置命令记在一个setup.md里换电脑或者重装系统时直接照着跑一遍比每次重新搜索教程快得多。我自己的清单就五条装 Node LTS、改执行策略、换镜像源、改全局目录、加 PATH。这五步做完Codex 和绝大多数 Node 工具都能顺利跑起来。