Codex Windows 安装前环境准备教程

Codex Windows 安装前环境准备教程

这篇教程带你在 Windows 上把 Codex 使用前的基础环境准备好。

前置教程：Codex 入门教程
如果你还不知道本站为什么先从安装开始，先看前置教程，再回到本篇。

先说清楚：这篇不是让你把所有开发工具都装满，而是先准备最常用、最容易影响 Codex 使用的几个东西：

• Windows 版本
• 命令提示符（cmd）
• Git
• Node.js LTS
• VS Code 或 Cursor
• 一个安全的练习项目目录
• 第一次只读启动任务

主要依据：OpenAI Codex 官方 Windows 文档、Node.js 官网、Git 官网、Windows 官方命令行与包管理文档、VS Code 官方 Windows 安装文档。
国内教程参考方式：只参考中文用户常见卡点和表达方式，下载地址、命令和版本判断以官方来源为准。

本篇目标

做完本篇后，你应该能做到：

1. 确认自己的 Windows 是否适合运行 Codex。
2. 正确打开命令提示符。
3. 安装并验证 Git。
4. 安装并验证 Node.js LTS 和 npm。
5. 准备一个适合 Codex 操作的项目目录。
6. 启动 Codex 后完成第一次只读项目分析。

适合谁

这篇适合：

• Windows 11 用户。
• 较新的 Windows 10 用户。
• 不熟悉终端、但愿意先从 cmd 开始的中文用户。
• 想用 Codex CLI 或 Codex Windows 桌面版做本地项目的人。
• 之前装过 Node.js、Git，但不确定环境是否正常的人。

如果你使用 macOS 或 Linux，这篇不是你的主线。本站后面会单独补其他系统。

先看结论

推荐环境是：

Windows 11
命令提示符（cmd）
Git for Windows
Node.js LTS
VS Code 或 Cursor
项目路径尽量简单，不要一上来放到很深、很乱、权限复杂的目录

新手最推荐的项目路径示例：

D:\code\demo-project

不推荐一开始放在：

C:\Windows\...
C:\Program Files\...
桌面\很长很长的中文目录\临时文件\最终版\新建文件夹\
网盘同步目录
压缩包里面

不是说中文路径一定不能用，而是新手阶段先把变量减少。等你跑通以后，再处理中文路径、空格路径、网盘同步这些复杂情况。

第 0 步：确认 Windows 版本

先按键盘：

Win + R

弹出“运行”窗口后，输入：

winver

然后回车。

你会看到一个 Windows 版本窗口。

推荐结果：

• Windows 11：最推荐。
• 较新的 Windows 10：可以尝试。
• 很旧的 Windows 10：不推荐，可能缺少现代终端能力。

OpenAI 官方 Windows 文档建议 Windows 11 作为最佳基线；较新的、完整更新过的 Windows 10 属于尽力支持。

如果你不知道自己的 Windows 10 算不算新，先继续做后面的验证。只要 cmd、Git、Node.js、Codex 能正常启动，就可以继续。

第 1 步：打开命令提示符

点击 Windows 开始菜单，搜索：

cmd

你通常会看到：

• 命令提示符
• cmd

点击打开即可。

打开后，输入：

ver

预期结果：你会看到 Windows 版本信息。

示例：

Major  Minor  Patch
-----  -----  -----
7      6      2

或者：

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      ...

这一步的目的不是研究系统细节，而是确认你能正常打开一个 Windows 原生命令行窗口。

第 2 步：安装 Git

Git 很重要。Codex 需要它来帮你查看改动、对比 diff、回滚错误、整理提交。

先检查你电脑有没有 Git：

git --version

如果看到类似结果：

git version 2.54.0.windows.1

说明 Git 已经安装。

如果提示：

'git' 不是内部或外部命令，也不是可运行的程序或批处理文件。

说明 Git 没装好，或者没加入 PATH。

推荐安装方式 A：官网下载

打开官网：

https://git-scm.com/install/windows

点击 Windows 版本下载。

安装时，新手可以一路使用默认选项。默认选项对本站教程够用。

安装完成后，关闭命令提示符，重新打开，再运行：

git --version

推荐安装方式 B：winget 安装

如果你的 winget 可用，也可以运行：

winget install --id Git.Git -e --source winget

安装完成后，同样关闭终端再重新打开，然后验证：

git --version

第一次设置 Git 用户名和邮箱

如果你以后要提交代码，建议先设置：

git config --global user.name "你的名字"

git config --global user.email "你的邮箱@example.com"

验证：

git config --global --list

预期结果里能看到：

user.name=你的名字
user.email=你的邮箱@example.com

注意：这里的邮箱不一定要公开展示，但要是你自己能识别的邮箱。

第 3 步：安装 Node.js LTS

如果你要做前端项目、Astro 静态站、Vue、Nuxt、React，Node.js 基本必备。

先检查：

node -v

再检查：

npm -v

如果都能显示版本号，说明已经安装。

示例：

v24.16.0

11.6.2

如果提示找不到 node 或 npm，说明还没装好。

推荐安装方式 A：Node.js 官网

打开官网：

https://nodejs.org/en/download

选择 LTS 版本。LTS 的意思是长期支持版本，更适合教程、项目和新手环境。

下载 Windows 安装包后双击安装。新手建议使用默认选项。

安装完成后：

1. 关闭所有命令提示符窗口。
2. 重新打开命令提示符。
3. 运行：

node -v

npm -v

推荐安装方式 B：winget 安装

如果 winget 可用，可以运行：

winget install --id OpenJS.NodeJS.LTS

安装完成后关闭终端，重新打开，再验证：

node -v

npm -v

如果 npm 提示不是内部或外部命令

你可能看到类似提示：

'npm' 不是内部或外部命令，也不是可运行的程序或批处理文件。

这通常不是权限策略问题，而是下面几种情况：

1. Node.js 没装好。
2. 安装后没有重新打开命令提示符。
3. PATH 还没刷新。

先关掉当前窗口，重新打开命令提示符，再运行：

node -v

npm -v

如果还是不行，回到 Node.js 官网重新安装 LTS 版本。

第 4 步：安装编辑器

推荐二选一：

• VS Code
• Cursor

如果你不知道选哪个，先装 VS Code。

VS Code 官网：

https://code.visualstudio.com/docs/setup/windows

安装时建议勾选：

• 添加到 PATH
• 右键菜单中添加“Open with Code”

不同版本安装器文字可能略有变化，核心目标是：以后你可以在项目文件夹里右键，用 VS Code 打开。

安装完成后，打开命令提示符，运行：

code --version

如果能显示版本，说明 VS Code 命令行可用。

如果提示找不到 code，不影响你手动打开 VS Code，但后面某些命令会不方便。可以重启电脑后再试。

第 5 步：准备一个安全项目目录

新建一个专门放练习项目的目录。

推荐：

mkdir D:\code

进入目录：

cd D:\code

确认当前位置：

cd

预期结果：

Path
----
D:\code

如果 D 盘不存在

可以用：

mkdir C:\code

然后：

cd C:\code

不要放到 C:\Windows、C:\Program Files 这类系统目录。

第 6 步：准备一个练习项目

如果你已经有项目，可以先用自己的项目，但要满足：

• 不是公司核心项目。
• 没有重要密钥。
• 最好已经用 Git 管理。
• 出错了也能恢复。

如果你暂时没有项目，可以先创建一个最小前端项目。这里用 Vite 举例。

在命令提示符里运行：

cd D:\code

如果你用的是 C:\code，就运行：

cd C:\code

创建项目：

npm create vite@latest codex-demo -- --template vanilla

进入项目：

cd codex-demo

安装依赖：

npm install

运行构建：

npm run build

预期结果：最后看到类似 built in ... 或构建成功信息。

如果 npm create 失败

常见原因：

• 网络不稳定。
• npm 源访问慢。
• Node.js 没装好。
• 当前目录没有写入权限。

先检查：

node -v

npm -v

如果版本正常，再换一个时间或网络重试。不要一上来改一堆 npm 配置。

第 7 步：初始化 Git

进入项目目录后运行：

git status

如果看到：

fatal: not a git repository

说明这个目录还不是 Git 仓库。

初始化：

git init

再运行：

git status

你会看到一堆未跟踪文件。

第一次提交：

git add .

git commit -m "chore: init demo project"

预期结果：Git 会生成一个初始提交。

再运行：

git status

如果看到：

nothing to commit, working tree clean

说明项目现在是干净状态，适合交给 Codex 做练习。

第 8 步：安装或打开 Codex

Windows 上你有两个常用选择：

• Codex Windows 桌面版
• Codex CLI

如果你是完全新手，建议先用桌面版。如果你已经能接受在 cmd 里输入命令，建议继续学 CLI。

选择 A：Codex Windows 桌面版

官方 Windows 桌面版可以通过 Microsoft Store 安装。官方文档也给出命令行安装方式：

winget install Codex -s msstore

安装完成后，在开始菜单搜索：

Codex

打开后登录你的账号。

选择 B：Codex CLI

如果你已经安装了 Codex CLI，在项目目录运行：

codex

如果提示找不到 codex，说明 CLI 还没安装或 PATH 没生效。后面会有单独一篇“Codex CLI 安装与登录”详细讲。

本篇重点是先把 Windows 基础环境准备好；如果你已经能打开 Codex，就继续做下面的只读任务。

第 9 步：第一次只读启动任务

无论你使用桌面版还是 CLI，第一次都不要让 Codex 改文件。

复制这段提示词：

请先只读分析当前项目，不要修改任何文件，不要运行会改变文件的命令。

请按下面格式回复：

## 当前环境
- 你看到的项目路径：
- 你判断这是项目根目录吗：
- 依据是什么：

## 项目结构
- 主要目录：
- 主要配置文件：
- 前端入口：
- 构建输出目录：

## 可用命令
- 安装依赖命令：
- 本地启动命令：
- 构建命令：
- 测试命令：

## 新手下一步
请推荐 3 个低风险任务。每个任务都要说明为什么低风险。

## 不确定的地方
不能确定就写“不确定”，不要猜。

发送后，检查 Codex 的回答。

你要确认：

1. 它没有修改文件。
2. 它能识别项目目录。
3. 它能找到 package.json。
4. 它能给出 npm run build 这类命令。
5. 它会写“不确定”，而不是乱猜。

第 10 步：确认没有文件被改

回到命令提示符，确保你还在项目目录。

运行：

git status

如果看到：

nothing to commit, working tree clean

说明本次只读任务没有产生文件改动。

如果看到有文件变化，运行：

git diff

不要提交，先确认变化内容。

常见问题

问题 1：命令提示符打不开或一闪而过

先从开始菜单打开，不要双击批处理文件。

搜索：

cmd

然后点击打开。

问题 2：winget 不是内部或外部命令

这说明 Windows 包管理器不可用。

解决方式：

1. 先通过官网下载 Git、Node.js、VS Code。
2. 后面有空再更新 Windows 或安装 App Installer。
3. 不要因为没有 winget 就卡住。

问题 3：node -v 成功，但 npm -v 报错

优先看是不是 Node.js 没装好，或者安装后没有重新打开命令提示符。

重新打开命令提示符后，再运行：

node -v

npm -v

问题 4：git status 提示不是 Git 仓库

说明当前目录没有 .git。

你要么进入真正的项目目录，要么运行：

git init

问题 5：路径里有中文会不会出问题

很多时候可以用，但新手阶段不推荐把第一个练习项目放在很复杂的中文路径里。

建议先用：

D:\code\codex-demo

等你跑通后，再尝试中文路径项目。

问题 6：Codex 要求访问网络或提升权限

先停下来，看它要做什么。

第一次只读分析项目时，一般不应该需要高权限，也不应该需要删除、覆盖、重置类命令。

如果你看不懂请求，就拒绝，并追问：

我不确定这个权限请求是否安全。请解释你为什么需要它、会执行什么命令、会修改哪些文件。如果不是必须，请换成只读方式。

做完这篇后，你应该看到的结果

做到这里，如果满足下面 8 条，就说明这篇安装准备已经跑通：

1. 你能打开命令提示符。
2. 你能看到 Windows 版本信息。
3. git --version 能正常输出。
4. node -v 能正常输出。
5. npm -v 能正常输出。
6. 你有一个练习项目目录。
7. npm run build 能成功，或者你知道失败卡在哪一步。
8. 你完成了一次 Codex 只读项目分析，并用 git status 确认没有乱改文件。

这篇你真正学会了什么

你不是只装了几个软件，而是搭好了 Codex 本地实战的最小环境：

cmd + Git + Node.js + 编辑器 + 干净 Git 状态 + 只读 Codex 任务

后面所有 CLI 实战都会默认你理解这套基础动作。

参考资料

• OpenAI Codex Windows 文档：https://developers.openai.com/codex/windows
• OpenAI Codex Windows App 文档：https://developers.openai.com/codex/app/windows
• Node.js 下载页：https://nodejs.org/en/download
• Git for Windows 下载页：https://git-scm.com/install/windows
• VS Code Windows 安装文档：https://code.visualstudio.com/docs/setup/windows

下一篇学什么

下一篇建议写：Codex CLI 安装与登录。

那一篇会专门讲 codex 命令怎么安装、怎么登录、怎么确认当前项目路径、怎么退出和重新进入。