企业官网建设流程全解析

如果你跟我一样，平时主力机就是 Windows，却又想在这台机器上把 AI 编程环境一次搭完整——终端里跑 Codex CLI 让 AI 直接改代码，本地用 Ollama 跑大模型做私有推理，顺手把 Docker、Redis、Spring AI 这些服务端组件全部接上——那这篇 Windows AI 编程环境从零搭建指南就是给你准备的。

2026 年 9 月我把一台刚装好系统的 Windows 笔记本从头到尾走了一遍这套流程，中间踩了不少坑，比如 codex 在 Windows 上安装未完成的经典问题、conda 和 pip 慢到怀疑人生、Docker Desktop 起不来、WSL2 内核版本不对导致各种玄学报错。所以这篇文章不做官方文档的翻译，而是把我实际执行过的命令、当时的选型逻辑、以及后来补回来的排查经验，按顺序整理出来，你照着一步步走就能复现。

适合谁看？两类人收获最大：一是一直在 Windows 上做前端或 Java 开发、想快速接入 AI 编程助手的同学；二是已经有基础 Python 能力、但没系统配置过整套开发环境的初学者。全程我会尽量说人话，专有名词保留英文原文，方便你搜官方文档。

1. 动手前先想清楚：Windows AI 编程环境到底有几层

1.1 一套环境的五个层次

在开始刷命令之前，你得先有一张整体地图，否则装到一半很容易陷入"装了个工具发现还缺另一个工具"的连环套。我把完整的 Windows AI 编程环境拆成五个层次：

1. 系统层：Windows 本体加 WSL2（Linux 子系统），这是所有工具的地基；
2. 通道层：终端、包管理器（winget）、Git，负责装软件、下代码、和远端仓库通信；
3. 运行时层：Python/conda、Node.js，现在绝大多数 AI 工具链都跑在这两个生态里；
4. AI 工具层：Codex CLI、VS Code 里的 AI 插件、提示词写法，这一层直接决定你写代码的效率；
5. 服务层：本地大模型（Ollama）、Docker 容器、Redis、Spring AI 后端，负责把 AI 能力变成可运行的服务。

这个分层不是理论框架，而是我排障时的实际思路。比如最典型的"codex windows 安装未完成"，问题大概率出在第二层（Node.js 版本或 npm 缓存）或系统层（权限、杀毒软件），而不是 AI 工具本身。一层一层定位，比到处搜"我这个报错是什么意思"快得多。

1.2 路线选择：纯 Windows 还是 WSL2

这是动手前最该做的一个决定。我的建议非常直接：

• 如果你主要用 Python 写脚本、跑 AI 工具的命令行接口、做数据分析，纯 Windows 加 Miniconda 就够了，不用上 WSL2；
• 如果你要编译 Linux 原生依赖、跑 Docker 容器、部署完整的多 Agent 服务，请直接上 WSL2，不要犹豫。

2026 年的 WSL2 已经是 Windows 官方标配，不是实验功能。而且 Docker Desktop 在 Windows 上默认就跑在 WSL2 里，你用纯 Windows 环境反而别扭。所以我的实际方案是两条腿走路：日常 Python 开发和 Codex 这类 CLI 工具放在 Windows 原生环境，涉及 Linux 兼容性和容器化的活全部丢进 WSL2。下面每一层我都会标注"在哪个环境执行"，避免你复制命令后找不到目录。

2. 地基层开工：终端、winget 与 Git

2.1 把终端先升级到能用的程度

Windows 自带的 cmd 和旧版 PowerShell 在 AI 工具面前基本是残废，先说终端。打开开始菜单搜索"Microsoft Store"，安装 Windows Terminal 和 PowerShell 7。如果你不想点鼠标，直接用 winget：

winget install --id Microsoft.WindowsTerminal -e --source winget winget install --id Microsoft.PowerShell -e --source winget

装完后把默认终端设为 Windows Terminal，默认 shell 设为 PowerShell 7。这一步别省：Codex CLI 和 Ollama 的输出是带颜色的流式内容，老终端会卡顿甚至乱码。

2.2 winget 的使用心得

winget 是 Windows 自带的包管理器，2026 年已经非常成熟。几个我常用的参数：

winget search ollama # 搜索软件 winget install --id Ollama.Ollama -e --source winget # 精确安装 winget upgrade --all # 统一升级

关键心得是-e和--source winget。-e表示精确匹配包名，避免搜出十几个相似结果；--source winget指定从官方源安装，而不是微软商店源，因为很多开发者工具（比如 Miniconda、Docker Desktop）在商店里的版本更新不及时。另外，winget 安装完的软件一般会自动写入 PATH，但你当前已经打开的终端不会刷新，必须新开一个窗口才能用，这个细节后面还会反复出现。

2.3 Git 与 SSH 密钥

AI 编程环境里 Git 的重要性被很多人低估。Codex 改代码时会生成 patch，如果你没有版本控制，AI 改坏了就只能手工回退；有了 Git，一条git checkout .就能把 AI 的"创作"全部还原。

安装和基础配置：

winget install --id Git.Git -e --source winget git config --global user.name "你的名字" git config --global user.email "你的邮箱" ssh-keygen -t ed25519 -C "你的邮箱" cat ~/.ssh/id_ed25519.pub

把公钥内容加到 GitHub 或 GitLab 的 SSH Keys 里。注意 ed25519 是 2026 年推荐算法，别再生成老的 RSA 4096 了。顺便说一句，配置好 SSH 后，后续 Codex 拉取私有仓库、提交 patch 都不需要反复输密码，体验差距很大。

3. WSL2 与 Ubuntu：把 Linux 运行时装进 Windows

3.1 安装 WSL2 的完整步骤

如果你只在 Windows 原生环境写 Python，可以跳过这一节。但只要你想跑 Docker 或部署 AI 服务，就绕不开 WSL2。安装过程现在非常傻瓜化，管理员身份打开 PowerShell：

wsl --install

重启后，系统会自动下载并安装 Ubuntu。如果默认发行版不是最新版，可以手动指定：

wsl --install -d Ubuntu-24.04 wsl --set-default-version 2 wsl -l -v

最后一条命令用来确认发行版 VERSION 显示为 2，如果是 1，说明 WSL2 没启用成功，需要去"启用或关闭 Windows 功能"里勾选"适用于 Linux 的 Windows 子系统"和"虚拟机平台"。首次启动 Ubuntu 会让你设置 Linux 用户名和密码，这个密码和 Windows 登录密码无关，别搞混了。

3.2 Ubuntu 初始化与国内镜像源

装完 Ubuntu 第一件事是换软件源，否则apt update能把人等崩溃。以清华 TUNA 镜像为例，编辑源文件：

sudo nano /etc/apt/sources.list

不同 Ubuntu 版本的源文件路径不同，24.04 之后改在/etc/apt/sources.list.d/ubuntu.sources，你按实际报错提示处理即可。把源地址前缀替换成https://mirrors.tuna.tsinghua.edu.cn/ubuntu/，然后：

sudo apt update && sudo apt upgrade -y

我建议顺手装上一组基础工具，后续基本都用得到：

sudo apt install -y build-essential curl wget unzip python3-pip

3.3 Windows 与 WSL2 的文件互通与性能陷阱

WSL2 的文件系统和 Windows 是打通的。在 WSL 终端里执行explorer.exe .可以打开当前目录的 Windows 资源管理器；在 Windows 资源管理器地址栏输入\\wsl$\Ubuntu-24.04\home\你的用户名也能直接访问 Linux 文件。

但这里有个特别重要的性能陷阱：不要把项目代码放在 Windows 文件系统（/mnt/c/...）里用 WSL 编译运行。WSL2 访问 Windows 侧文件要经过 9P 协议转换，读写性能差好几倍，尤其是 Node 项目动辄几万个文件，跑起来会卡到怀疑人生。正确姿势是把 AI 项目的代码放在 Linux 文件系统（比如~/projects）下，需要和 Windows 交换文件时再通过\\wsl$路径操作。

另外，新版 WSL2 默认支持 systemd。你可以检查/etc/wsl.conf里是否有[boot] systemd=true配置，有了 systemd，后面在 WSL 里跑 Docker 服务就会自然很多。

4. Python 与 Node 双运行时：Miniconda 安装到虚拟环境管理

4.1 Miniconda 完整安装步骤

Python 环境管理我毫不犹豫推荐 Miniconda，而不是直接装官方 Python。原因很简单：conda 不只是 Python 包管理器，它还能管理虚拟环境和底层依赖（比如 CUDA 相关的库），对 AI 项目这种依赖冲突大户来说几乎是必需品。

安装有两种方式。命令行可以用 winget：

winget install --id Anaconda.Miniconda3 -e --source winget

也可以去官网下载安装包，图形界面点下一步。安装时有两个选项需要特别注意：

• 选择"Install for me"（仅当前用户），避免权限问题；
• 安装路径务必是全英文，比如C:\Users\你的英文用户名\miniconda3，千万不要装到带中文的用户目录下，否则后面 conda 会间歇性抽风。

装完重新打开终端，执行conda --version验证。如果提示找不到命令，多半是没加入 PATH，去系统环境变量里把C:\...\miniconda3\Scripts加进去。

4.2 conda 虚拟环境：AI 项目不打架的关键

我见过太多人拿到环境后直接pip install torch transformers langchain一把梭，结果不同项目互相把依赖顶坏，最后只能重装系统。虚拟环境就是干这个的：

conda create -n ai python=3.12 -y conda activate ai python -V

这个命令创建了一个名为 ai 的独立环境，里面用 Python 3.12。以后所有 AI 项目都先conda activate ai再装包，和全局环境隔离，删除也方便：conda env remove -n ai。多项目并行时就把数字 3.12 换成项目要求的具体版本，一个项目一个环境，互不干扰。

conda 默认源在国内速度不稳定，建议配置镜像：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --set show_channel_urls yes

pip 同样需要配置镜像源：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

4.3 Node.js 与 npm 镜像

Node.js 是 Codex CLI、各类前端 AI 工具链的基础。用 winget 安装 LTS 版本：

winget install --id OpenJS.NodeJS.LTS -e --source winget node -v npm -v

npm 默认源同样是慢点重灾区，一句话搞定：

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

把输出和https://registry.npmmirror.com比对，一致就说明配置成功。这一步做完，后面全局安装@openai/codex会快非常多。

4.4 环境变量检查清单

运行时层装完后，打开一个新的 PowerShell 窗口，逐条执行下面几个命令，确认路径没有重复或缺失：

where python where conda where node where npm where git

每条命令应该只输出一个路径，如果输出了两个或更多，说明你系统里存在多个 Python 或 Node，后面各种"版本不对"的问题就是从这里开始的。多版本并存不是不能用，但你需要明确知道当前终端到底调用了哪个解释器。排查时记住一个原则：改完环境变量必须新开终端，别在旧窗口里死等。

5. AI 编程助手接入：Codex CLI 从安装到日常使用

5.1 Codex CLI 到底能干什么

Codex CLI 是 OpenAI 开源的终端 AI 编程助手，也是 AI Agent 这个概念的典型落地形态。它和 IDE 里的 Copilot 类插件不同：Copilot 更像"更聪明的自动补全"，而 Codex 是"给你一个任务，它自己去读代码库、改文件、跑测试、最后把结果拿给你看"。

在 Windows 上装 Codex CLI，前提就是上一节的 Node.js 环境。

5.2 安装与登录全流程

直接全局安装：

npm install -g @openai/codex codex --version codex login

codex login会弹出浏览器让你授权，登录成功后终端会显示账号信息。到这里，一个最小可用的 AI 编程助手就装好了。

接下来是很多人在 Windows 上卡住的环节。如果你遇到"codex windows 安装未完成"，也就是安装过程停在某个依赖上、最后提示失败或命令找不到，按这个顺序排查：

1. 检查 Node 版本：node -v，必须是大版本大于等于 18 的 LTS 版本，旧版本很多依赖装不上；
2. 清理 npm 缓存：npm cache clean --force，然后重装。安装中断产生的半成品缓存是头号嫌疑人；
3. 用管理员权限重试：右键 PowerShell 选择"以管理员身份运行"，再执行一次安装命令；
4. 检查杀毒软件：Windows Defender 或第三方安全软件可能拦截 npm 下载的可执行文件，去隔离区找回，或把 npm 全局目录加入白名单。

这个排查顺序是我实测下来最有效的，按顺序做基本都能解决。

5.3 让 Codex 真正干活的项目配置

Codex 干活的依据是项目根目录下的AGENTS.md文件。这个文件相当于给 AI 的"入职手册"，内容可以包括：

• 项目结构说明：哪些目录是核心源码，哪些是生成文件；
• 代码规范：缩进风格、命名规则、提交信息格式；
• 常用命令：如何运行测试、如何构建、如何 lint。

我在项目里写的 AGENTS.md 大概长这样：

# 项目说明 这个仓库是一个 FastAPI 后端服务，核心代码在 app/ 目录。 # 命令 测试: python -m pytest 启动: uvicorn app.main:app --reload # 规范 - 新增接口必须写类型注解 - 提交信息用 gitmoji 风格

写好之后，在项目目录里执行：

codex "新增一个健康检查接口，并补上测试"

Codex 会先输出它的执行计划，然后逐文件修改，每个改动都需要你确认。第一次用建议保持在交互模式，看清楚它改了什么再放行。等完全信任了，再考虑--approval-mode full-auto这类自动模式。还有一个我强烈推荐的习惯：每让 Codex 改一个功能，就立刻git diff看变更、git commit打一个还原点。它改坏了，你永远有后悔药。

5.4 AI 编程提示词的实用写法

提示词不用写得多华丽，但要信息完整。我总结的四个要素：任务、范围、约束、验收标准。

差的提示词：

给我写个登录功能。

好的提示词：

在 app/auth.py 中实现基于 JWT 的登录接口，使用项目已有的用户模型，密码用 bcrypt 加密，返回 access token 和 refresh token。要求补上对应的 pytest 测试，测试通过后才能提交。

两者的差距在于：AI 不需要猜你的意图，也几乎没有机会自由发挥跑偏。记住，Codex 这类 Agent 工具的幻觉往往不是因为模型不行，而是因为指令里的信息不够它决策。

5.5 VS Code 插件作为第二梯队

Codex CLI 强在任务执行，但日常快速补全、改一个函数签名这种事，用 VS Code 加 AI 插件更顺手。我在 Windows 上的组合是：VS Code + GitHub Copilot 做实时补全，Continue 插件接本地 Ollama 模型做隐私场景的对话。这样"代理式任务"和"交互式补全"两条线都有覆盖，速度和质量都能兼顾。

6. 本地大模型跑起来：Ollama 部署、模型选型与硬件边界

6.1 为什么要在本地跑模型

很多人问：有云端的 Codex 和 ChatGPT 了，为什么还要在本地跑大模型？我的理由很实际：一是代码有保密要求，不能发到云端；二是断网时本地模型还能继续干活；三是调 API 有费用，而本地推理一次只有电费。

6.2 Ollama 安装与模型拉取

Ollama 是目前 Windows 上部署本地模型最省心的方案。安装照旧：

winget install --id Ollama.Ollama -e --source winget ollama --version

然后拉取一个代码方向的中小模型：

ollama pull qwen2.5-coder:7b ollama run qwen2.5-coder:7b

第一条命令下载模型，第二条进入交互对话。模型参数以 Ollama 官方模型库的最新列表为准，我这里用的是我当时实测的模型名，你拉取前可以先ollama list看看本地已有的模型，也可以去官网搜索更新的版本。模型下载完默认存在C:\Users\你的用户名\.ollama\models，如果 C 盘空间紧张，可以通过设置OLLAMA_MODELS环境变量改到其他盘。

6.3 模型选型与硬件对照表

本地模型不是越大越好，硬件撑不住反而连小模型都不如。我把常见参数量级的硬件需求整理成了表格，方便你按机器配置做选择：

这里说的"量化"是模型压缩的术语，Ollama 默认拉取的模型已经是最常用的量化版本，你不需要关心细节，只需要记住：显存不够的时候，Ollama 会把模型塞进内存，用 CPU 跑，速度会慢一个数量级。如果你的 NVIDIA 显卡没被识别，先更新显卡驱动，再执行ollama -v看日志，驱动版本太旧是本地模型速度慢的最常见原因。

6.4 把本地模型接进 AI 编程工具链

Ollama 启动后会在本机开一个 API 服务，默认地址是http://localhost:11434。你可以用 curl 验证：

curl http://localhost:11434/api/tags

返回一长串 JSON 就是正常。这个 API 就是本地模型的"插座"，Codex CLI 和 Continue 插件都可以接过来。

Continue 插件配置 Ollama 比较直观，在设置里把 provider 选成 Ollama，填上模型名就够了。Codex CLI 则需要在配置文件里自定义 model provider，指向 Ollama 的地址。这类配置的具体写法随版本更新变化较快，我建议以你机器上codex --help输出的配置说明为准。核心思路是一致的：把 OpenAI 兼容的 base URL 换成http://localhost:11434/v1。

需要做好心理预期的是，本地 7B 模型的代码能力远不如云端的大模型，它更适合隐私敏感场景和离线场景。我把本地模型定位为"助手的手下"，先让它干粗活，关键决策还是交给云端大模型。

7. Docker、Redis 与 Spring AI：服务端的 Windows 解法

7.1 Docker Desktop 的正确安装姿势

Docker 在 Windows 上几乎等价于 WSL2，因为 Docker Desktop 的引擎就跑在 WSL2 里。安装：

winget install --id Docker.DockerDesktop -e --source winget

装完首次启动，在 Settings -> General 里确认勾选了"Use WSL 2 based engine"。这一步很重要：选 Hyper-V 引擎也不是不能用，但资源占用高、启动慢，和 WSL2 的轻量性完全没法比。

然后到 Settings -> Resources 里给 WSL2 分配内存和 CPU。默认配置往往偏保守，如果你的机器是 32GB 内存，给 Docker 分 8~16GB 都合理，否则跑 Redis 和多个容器时会频繁 OOM。

验证安装：

docker version docker run hello-world

如果docker run报错，大概率是 WSL2 内核版本太旧，先执行wsl --update再试。

7.2 用 Docker 跑 Redis

AI 应用里 Redis 的用途很多：缓存大模型响应、做 Agent 会话存储、当轻量消息队列。用 Docker 启动最省事：

docker run --name redis -p 6379:6379 -d redis:7 redis-cli ping

redis-cli如果提示没有命令，可以直接用 Docker 里自带的客户端：

docker exec -it redis redis-cli ping

返回PONG就说明 Redis 可用。这个容器会一直后台运行，docker stop redis停止，docker start redis再启动，不需要每次新建。如果你做 Agent 开发需要向量检索能力，可以用 Redis Stack 镜像替代原生 Redis，它自带了搜索和向量模块，一个端口解决多个需求。

7.3 Spring AI：Java 生态接入本地模型的路径

如果你是 Java 后端工程师，不想为了 AI 去重学一套 Python 技术栈，Spring AI 就是标准答案。它是 Spring 生态里专门做 AI 应用集成的框架，思路和 Spring Data、Spring Cloud 一脉相承，把各种模型提供方封装成了统一的客户端接口。

Maven 依赖：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-ollama-spring-boot-starter</artifactId> </dependency>

配置文件application.yml：

spring: ai: ollama: base-url: http://localhost:11434 chat: options: model: qwen2.5-coder:7b

然后在 Service 里注入客户端：

@Autowired private ChatClient chatClient; public String askAi(String question) { return chatClient.call(question); }

看到没有，代码量和调一个普通 HTTP 接口差不多。Spring AI 最大的价值在于：今天你接 Ollama，明天想换云端模型，只需要改配置，业务代码一行不用动。用 winget 装好 OpenJDK 和 Maven 后，这个流程在 Windows 原生环境直接就能跑通。Maven 依赖下载慢的话，去阿里云镜像站找到 settings.xml 的配置方式，把 mirror 指向国内地址即可。

8. 踩坑实录：我从零搭建时遇到的五个拦路虎

8.1 codex windows 安装未完成

这是我在整个过程中卡最久的问题。现象是 npm 安装进度条走到某个包就停住，等一会儿直接报错退出，codex --version提示找不到命令。按"先版本、再缓存、后权限、最后杀软"的顺序排查，最终确定是 npm 缓存里存了损坏的半成品包。解决办法就是npm cache clean --force后重装。如果你也遇到，别急着重装系统和换网络，先执行这一步。

8.2 conda 和 pip 慢到怀疑人生

不配置镜像源的话，conda 装一个 PyTorch 可能要半小时起步。配置镜像的命令上面都写了，这里再强调一个细节：pip 配置的是global.index-url，但如果你在虚拟环境里用的是pip install，配置同样生效，不需要每个环境单独设置。另外 conda 的 channels 配置是将镜像地址追加到已有 channel 列表，执行conda config --show channels可以确认是否生效。

8.3 Docker Desktop 起不来

我遇到的情况是启动后一直转圈，最后提示 WSL 相关错误。排查链路是：先执行wsl --status看内核版本，然后wsl --update升级，再确认 BIOS 里虚拟化已开启。Docker Desktop 还有一种常见情况是第一次启动需要管理员权限，右键"以管理员身份运行"一次，之后就能正常开机自启了。

8.4 中文路径引发的玄学问题

这是个老生常谈但每年都有人踩的坑。如果你的 Windows 用户名是中文，Miniconda 默认路径就会带中文，conda 创建环境时偶尔会报编码错误。Docker 的默认数据目录在C:\Users\中文用户名\AppData\Local\Docker，也容易出权限问题。最稳妥的做法是：把 Miniconda 和 Docker 数据目录手工改成英文路径，项目目录一律用英文命名，能省掉一大部分"为什么别人能行我不行"的时间。

8.5 改了环境变量却不生效

很多工具装完提示"请重启终端"，但重启后还是不生效。这是因为环境变量在 Windows 里分"系统级"和"用户级"，修改后只对新启动的进程生效，你打开一个旧的 PowerShell 标签页，它继承的还是改之前的变量。我的习惯是：改完环境变量，关掉所有终端窗口，重新打开一个，执行where python确认真实路径，而不是凭猜。

最后分享一点个人体会。整个 Windows AI 编程环境搭完，我最满意的地方不是每个工具都装好了，而是排障思路变清晰了：任何问题先定位到五层结构里的某一层，然后在这一层做最小化验证，而不是见一个坑跳一个坑。这套环境用下来，Codex 帮我处理了不少枯燥的 CRUD 和测试补全，本地 Ollama 模型则负责那些不能外传的敏感代码分析，各司其职。如果你也打算在这个方向上走下去，我的建议是先把地基打牢，再去追各种新工具，地基稳了，后面换什么工具都是顺手的事。