Windows 上做 AI 开发已经不是什么稀奇事了但每次有朋友问我“我想在 Windows 上跑 AI 项目到底该怎么开始”我都能感觉到那种无从下手的焦躁。网上教程要么只讲某个单一环节要么默认你用 Linux/macOS真正从零开始、把 Python、Git、VS Code、Docker/WSL、AI 编程助手这些串成一条完整链路的 Windows 实战指南反而很难找。这篇就基于我近期从一台裸机 Windows 环境开始搭建 AI 编程环境的全过程把思路、步骤、参数选择和踩过的坑一次说清楚适合刚入门想系统搭环境的新手也适合想把手头 Windows 机器整理成 AI 开发机的老手做个对照。1. 整体思路与环境选型先想清楚再动手1.1 这套环境具体要解决什么问题很多人觉得搭环境就是把 Python 装上、能跑 hello world 就行但真正开始做 AI 相关开发时会发现需求远不止这些。你要用 Jupyter Notebook 做实验要用 Git 做版本管理要用 AI 编程助手辅助写代码要跑本地模型或者连接大模型 API还可能要把 Redis 当缓存、把 Elasticsearch 当知识库检索这些组件在 Windows 上的安装方式各不相同而且相互之间有版本依赖关系。我这套环境的目标非常明确在一台全新的 Windows 电脑上从安装 Python 开始一直到能正常使用 AI 编程插件、本地启动 Redis 和 Elasticsearch、通过 Docker/WSL 跑 Linux 容器最终能跑通一个完整的 AI 编程 demo。整个过程不涉及高端硬件要求也不需要复杂的网络配置纯粹是软件层面的环境搭建和验证。1.2 为什么选这套工具组合先交代一下我的选型逻辑。语言层面Python 是 AI 生态的绝对主力必须最先装好同时把 C 语言编译环境和 JDK 17 备好因为很多 Python 包在 Windows 上需要编译而 Elasticsearch 等 Java 系组件离了 JDK 根本起不来。编辑器选 VS Code插件生态最全对 AI 编程助手的支持也最成熟。版本管理用 Git配合 Windows Terminal 一起用命令行体验会好很多。容器环境是重头戏。Windows 上跑 Linux 容器有两条路线一条是纯 Docker Desktop另一条是 WSL 2 里面装 Docker Engine。我最终选择 Docker Desktop WSL 2 的组合原因后面细说。AI 编程工具方面我装了 GitHub Copilot 作为日常主力同时试了 OpenAI Codex 桌面版两者各有侧重我后面会给出对比。这套组合的核心思路是能用 Windows 原生组件解决的不额外引入抽象层必须用 Linux 环境的地方统一通过 WSL 2 中转。这样既能保证日常开发的流畅度又不会在关键项目上被 Windows 和 Linux 的差异卡住。2. 基础环境搭建Python、Git、VS Code 与系统组件2.1 Python 安装与版本选择Python 安装看似简单但很多坑就藏在细节里。我建议直接去 Python 官网下载 Windows installer不要用 Microsoft Store 版本后者有文件路径权限限制后续 pip 装全局包的时候容易出问题。选版本时需要注意当前时间点建议选择 3.11 或 3.12 的稳定版尽量别用最新的 3.13因为一些 AI 相关的底层库还没有完全跟上。安装时有一个关键勾选项Add python.exe to PATH一定要勾上。很多人装完 Python 后在命令行敲python没反应八成就是这一步漏了。我习惯选择自定义安装把安装路径改到C:\Python311这种不含空格的目录避免后续一些老牌工具解析路径时出问题。# 安装完成后验证版本 python --version pip --version # 建议顺手升级 pip python -m pip install --upgrade pip2.2 Git 安装与终端配置Git for Windows 是必须的AI 编程这块已经离不开 Git 工作流。下载安装包时一路 next 就行但到了Adjusting your PATH environment这一步记得选Git from the command line and also from 3rd-party software这样 VS Code 和 AI 插件才能正确找到 Git。还有个很多人忽略的点默认安装的 Git Bash 用的是 mintty 终端在 Windows Terminal 里有时显示中文会乱码。我建议把 Git 的默认分支名设置为main并在 Git Bash 的设置里把字符编码改成 UTF-8。另外安装完成后建议立刻配置用户信息否则第一次 commit 会报错。git config --global user.name 你的用户名 git config --global user.email 你的邮箱 git config --global init.defaultBranch main2.3 VS Code 与必要插件VS Code 装好后我先说几个必装插件Python 扩展ms-python.python提供调试和智能提示Pylance 做语言服务GitLens 看代码历史非常方便还有 Remote - WSL 用于连接 WSL 环境。这几个是基础后面的 AI 编程插件咱们单独讲。一个容易被忽略的是设置同步。登录 GitHub 账号后开启 Settings Sync换机器时环境一键恢复我在重装系统以后靠着这个省了不少时间。装插件之前先去File Preferences Settings里把files.autoSave设为onFocusChangeeditor.formatOnSave设为trueterminal.integrated.defaultProfile.windows设为 Git Bash这些都是我做 AI 开发时的标配。2.4 按需补充C 语言环境与 JDK 17C 语言环境不是 AI 开发的主项但 Python 生态里很多包在 Windows 上安装时如果没有编译工具链会直接报Microsoft Visual C 14.0 is required。这个问题的标准解法是安装 Visual Studio 2022 Build Tools不需要装完整版 VS只需要在组件里勾选MSVC v143和Windows 10/11 SDK。如果你单纯想学 C 语言也可以装 MinGW-w64但做 AI 开发我更推荐前者。JDK 17 则是为 Elasticsearch 和部分 Java 系 AI 工具准备的。下载jdk-17_windows-x64_bin.exe安装后记得配置环境变量# 系统环境变量新增 JAVA_HOMEC:\Program Files\Java\jdk-17 # PATH 中新增 %JAVA_HOME%\bin配置完在命令行执行java -version确认输出中有17即可。这一步不装也能用纯 Python 做 AI但一旦你想尝试 Spring AI 或者在本地跑 Elasticsearch还是要回头补上。3. AI 编程辅助工具接入从 Codex 到 Copilot3.1 桌面端 AI 编程工具怎么选AI 编程是这两年变化最快的方向选择非常多。我目前主力用的工具是 GitHub Copilot另外也在尝试 OpenAI Codex 桌面版和 Cursor。它们各有各的适用场景我把自己实际使用的体感写在对比表格里方便你按需选择。工具安装方式核心特点适合场景GitHub CopilotVS Code 插件代码补全极其顺滑上下文理解好日常开发主力Codex 桌面版独立客户端云端沙箱执行可以跑完整任务复杂任务、跨项目操作Cursor独立编辑器基于 VS Code 内核AI 能力深度集成重度 AI 协作开发ContinueVS Code 开源插件可本地配置模型支持私有化对数据安全要求高的场景一个明确的建议不要贪多先用好一个工具。Copilot 的补全能力在写重复性代码和模板代码时效率提升非常明显Codex 在需要 AI 帮你完整实现一个功能模块时更有优势两者不冲突可以同时装。3.2 安装与认证配置GitHub Copilot 的安装流程很直接在 VS Code 扩展市场搜索GitHub Copilot点击安装然后在左下角账户图标登录 GitHub 账号选择授权即可。如果遇到无法登录的情况多半是网络问题跟代理没有关系的时候检查一下系统代理设置或者重启 VS Code 再试一次。Codex 桌面版在 Windows 上安装时需要注意当前版本对 Windows 10 1809 以上系统支持较好。我建议先确认系统版本再去官方网站下载对应的codex-setup.exe。安装完成后的首次登录需要用一个 OpenAI 账号做设备授权整个过程会生成一个本地密钥文件存放在用户目录下。实际使用时Codex 会启动一个云端沙箱来执行生成的代码这样本地不会残留乱七八糟的依赖但也意味着你需要在本地准备一个项目目录让 Codex 去读写。3.3 AI 编程提示词的使用技巧AI 编程工具能不能发挥效果一半取决于工具本身另一半取决于提示词。这里有几个我实际验证过的高效技巧。第一给 AI 指定角色和上下文比如直接说“你是一名精通 Python 和 FastAPI 的工程师请帮我实现一个用户登录接口”比单纯说“帮我写个登录接口”效果好得多。第二把需求拆小一次只让 AI 生成一个函数或一个模块而不是让它一口气生成整个项目。第三给出具体的输入输出约束比如“函数的输入是用户 ID输出是对应用户信息字典缺少时抛出异常”AI 生成的代码质量会明显上升。另外我强烈建议在项目里维护一个PROMPT.md文件把常用的提示词模板、项目结构说明、代码风格要求写进去。很多 AI 工具支持把项目文档作为上下文这样每次对话就不用重复交代背景了这个习惯在团队协作时尤其有用。4. 本地服务与依赖组件Redis、Elasticsearch 与 WSL/Docker4.1 WSL 与 Docker Desktop 的配合在 Windows 上做 AI 开发总是绕不开 WSL 和 Docker。我之前走过一段弯路最初以为在 Windows 上直接装 Docker Desktop 就够了结果发现很多 AI 项目的依赖是 Linux 专属的比如某些 Python 包在 Windows 上根本没有预编译版本。后来我改成 Docker Desktop WSL 2 的组合Docker Desktop 负责管理容器WSL 2 提供 Linux 内核两者无缝配合。安装顺序上建议先装 WSL 2 再装 Docker Desktop。在管理员 PowerShell 里执行wsl --install这个命令默认会启用 WSL 2 并安装 Ubuntu 发行版。安装完成后重启进入 Ubuntu 终端更新软件源后就可以正常使用 Linux 环境了。之后安装 Docker Desktop for Windows安装过程中会提示是否使用 WSL 2 backend选择启用。Docker Desktop 会自动配置与 WSL 的集成不需要额外手动操作。4.2 Redis for Windows 的安装与启动Redis 在 AI 开发里主要用于缓存和消息队列。官方已经不再维护 Windows 原生版本但社区维护的版本仍然可用我使用的是tporadowski/redis提供的 Windows 移植版。下载 zip 包解压到C:\Redis后直接双击redis-server.exe就能启动但更好的做法是把 Redis 注册成 Windows 服务# 在 C:\Redis 目录下执行 redis-server --service-install redis.windows-service.conf --service-name Redis redis-server --service-start --service-name Redis注意redis.windows-service.conf和普通的redis.conf有几处不同。服务版配置里默认daemonize yes并且日志输出到文件而不是控制台。如果启动后连接不上先检查 6379 端口是否被占用常见问题和排查方法我放在后文。4.3 Elasticsearch 启动与 Java 环境关系Elasticsearch 在 AI 应用里通常用来做向量检索或者全文检索配合大模型实现 RAG检索增强生成。启动 ES 前JDK 17 一定要装好因为 ES 8.x 版本强制要求 JDK 17。解压elasticsearch-8.x-windows-x86_64.zip后在config/elasticsearch.yml里推荐设置如下cluster.name: ai-local node.name: node-1 network.host: 127.0.0.1 http.port: 9200 discovery.type: single-node然后运行bin/elasticsearch.bat启动。首次启动会生成一个elastic用户的密码和证书建议记下来。启动成功后访问http://localhost:9200能看到集群信息 JSON 就说明成功了。这里有一个非常常见的坑启动窗口一闪而过通常是 JDK 环境变量没配对或者是内存不足需要在jvm.options里把-Xms和-Xmx调低比如改成512m。4.4 小项目里的 Spring AI 接入思路如果你用的是 Java 技术栈Spring AI 是值得关注的方向。它的定位是 Spring 生态的 AI 开发框架可以统一对接 OpenAI、阿里云通义千问、智谱等多家大模型 API封装了 ChatClient、EmbeddingModel 等一系列接口。在 Windows 上开始 Spring AI 开发只需要在 Spring Initializr 里添加Spring AI依赖然后把 API Key 配置在application.yml里就行。不过我必须提醒一下目前的 Spring AI 版本迭代比较快API 变动明显生产环境使用要谨慎。我在本地试过用 Spring AI 接 Elasticsearch 做向量检索整体链路是通的但调试成本比 Python 生态高不少。如果你不是非用 Java 不可快速验证阶段建议还是走 Python 路线Java 路线更适合有历史系统需要集成 AI 能力的场景。5. 实操过程从零跑通一个本地 AI 编程 demo5.1 创建虚拟环境并安装依赖理论讲完下面进入实操。我这次的目标是在新搭建的环境里用 AI 编程助手生成一个简单的语义搜索服务并跑通本地验证。这个 demo 会用到 Python、FastAPI、Redis 缓存和 Elasticsearch 存储文档覆盖面比较全很适合作为环境验证项目。先在项目目录下创建虚拟环境这一步务必养成习惯别把依赖装到全局mkdir ai-demo cd ai-demo python -m venv venv venv\Scripts\activate激活虚拟环境后命令行前面会出现(venv)标记。然后安装依赖pip install fastapi uvicorn redis elasticsearch sentence-transformersuvicorn是 FastAPI 的 ASGI 服务器sentence-transformers用来生成文本向量这个操作会拉取一个约 400MB 的模型文件首次运行会比较慢耐心等待即可。5.2 用 AI 工具生成并调试代码依赖装好后我打开 VS Code用 Copilot 生成了核心代码。我的提示词是这样的“请用 FastAPI 实现一个文本语义搜索服务包含两个接口/index接收 JSON 文本并存入 Elasticsearch/search接收查询文本并返回相似度最高的结果Redis 用于缓存查询结果向量模型使用 sentence-transformers 的 paraphrase-MiniLM-L6-v2。”Copilot 会生成一段代码但直接跑你会发现几个问题索引不存在、Redis 连接失败、向量维度不匹配。这些都需要手动调整。我自己动手改了几处关键的代码长这样from fastapi import FastAPI, HTTPException from pydantic import BaseModel from elasticsearch import Elasticsearch import redis from sentence_transformers import SentenceTransformer app FastAPI() model SentenceTransformer(paraphrase-MiniLM-L6-v2) es Elasticsearch(http://localhost:9200) r redis.Redis(hostlocalhost, port6379, decode_responsesTrue) INDEX_NAME docs VECTOR_DIM 384 # MiniLM-L6-v2 输出维度 class Doc(BaseModel): text: str app.post(/index) def index_doc(doc: Doc): vector model.encode(doc.text).tolist() es.index(indexINDEX_NAME, document{ text: doc.text, vector: vector }) r.delete(search_cache) return {status: ok} app.post(/search) def search(doc: Doc): cache r.get(fsearch:{doc.text}) if cache: return {cache: True, result: cache} vector model.encode(doc.text).tolist() result es.search(indexINDEX_NAME, knn{ field: vector, query_vector: vector, k: 3, num_candidates: 10 }) hits [hit[_source][text] for hit in result[hits][hits]] r.set(fsearch:{doc.text}, str(hits), ex300) return {cache: False, result: hits}注意这里VECTOR_DIM 384这个值必须和模型输出的向量维度一致否则 ES 会报映射错误。这是最容易踩的坑我在网上看到不少人卡在这。如果遇到字段类型冲突可以去 ES 的 Dev Tools 里删掉旧索引重建或者手动创建带dense_vector映射的索引。5.3 联调本地服务代码写好后启动服务之前确保 Redis 和 Elasticsearch 都在运行。然后执行uvicorn main:app --reload --host 0.0.0.0 --port 8000在浏览器打开http://localhost:8000/docs能看到 FastAPI 自动生成的 Swagger 文档这是个很好的自测入口。先调/index接口存入两条测试文本再调/search查询如果返回的结果语义相关度合理整个环境就算验证通过了。我还额外测试了缓存效果连续两次调用/search第二次返回的cache字段是true说明 Redis 生效了。到这里整套 Windows AI 编程环境就全部打通了从 Python 到 Git 到 VS Code 到 AI 助手再到本地服务组件是一个完整可复用的链路。5.4 环境验证清单为了帮你确认自己的环境是否搭好我整理了一份验证清单照着过一遍可以省很多排查时间检查项验证命令/操作预期结果Pythonpython --version输出 3.11 或 3.12Gitgit --version输出版本号JDKjava -version输出 17 相关版本Dockerdocker --version输出版本号Redisredis-cli ping返回 PONGElasticsearch访问 localhost:9200返回 JSON 信息AI 助手VS Code 中测试代码补全出现 AI 建议6. 常见问题与排查技巧实录6.1 命令行窗口一闪而过Windows 上启动脚本时窗口一闪而过通常意味着程序启动报错。这个问题的排查思路是先手动在终端里执行同样的命令看错误输出。比如 ES 启动失败执行bin\elasticsearch.bat就能看到具体报错信息常见原因是 JDK 未安装或版本不匹配。如果是redis-server一闪而过多半是配置文件里的logfile路径不存在手动创建对应目录就能解决。另一个高级技巧是给脚本加暂停在.bat文件末尾加一行pause这样即使出错窗口也会停留在原地你能看到完整的错误信息。这个方法虽然土但非常有效。6.2 端口被占用AI 开发中端口被占用是最高频的问题。Elasticsearch 的 9200 端口、Redis 的 6379 端口、FastAPI 的 8000 端口都容易冲突。Windows 下定位端口占用极其简单netstat -ano | findstr :9200findstr是 Windows 下等价于 Linuxgrep的命令。查到 PID 后在任务管理器里找到对应进程结束即可。如果是系统关键进程占用了端口那就换端口比如 ES 修改http.portRedis 启动时加--port 6380不用死磕默认端口。6.3 WSL 与 Docker 启动异常Docker Desktop 偶尔会出现启动后一直转圈的情况。先确认 Windows 功能里Virtual Machine Platform和Windows Subsystem for Linux是否开启这个可以在管理员 PowerShell 里执行wsl --status检查。如果 WSL 版本是 1需要先升级到 2wsl --set-version Ubuntu-22.04 2另一类问题是 Docker 容器内无法访问 Windows 宿主机上的服务。Docker Desktop 的 WSL 模式下容器访问宿主机不能直接用localhost要使用host.docker.internal这个特殊域名这个是很多新手搞不定的点。6.4 Windows 安全相关配置Windows 自带的 Defender 防火墙有时会拦截本地服务的网络请求尤其是第一次启动uvicorn或redis-server时系统会弹出允许访问网络的提示如果点了取消后续连接就会一直失败。处理方法是去Windows 安全中心 防火墙和网络保护 允许应用通过防火墙找到对应进程并勾选专用网络。另外如果把 Windows 安全日志作为 AI 安全分析的数据源需要在事件查看器里启用相应的日志记录默认配置下部分日志记录是不完整的。这一步虽然不是搭建环境的必需环节但对于做安全相关 AI 分析的人来说是个关键点。6.5 xftp 连接 Windows 的问题最后分享一个跟 AI 开发相关的周边问题。很多人会用 XFTP 从 Windows 机器传文件到 Linux 服务器反过来如果要连 Windows 机器需要开启 OpenSSH Server。在管理员 PowerShell 里执行Get-WindowsCapability -Online | Where-Object Name -like OpenSSH.Server*查看安装状态如果没安装用Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0安装。安装后启动服务并设为自动启动Start-Service sshd Set-Service -Name sshd -StartupType Automatic注意 Windows 的 OpenSSH 默认使用系统用户名和密码认证连接时用户名就是 Windows 用户名密码就是开机密码。如果你的 Windows 账户是微软账户可能需要用微软账户的邮箱格式来登录这是个很容易忽略的细节。6.6 其他高频问题速查表问题现象可能原因解决方法pip 安装慢或超时默认源在国外配置清华源或阿里源VS Code 中文乱码终端编码问题设置terminal.integrated.profiles.windows为 UTF-8Docker 拉取镜像失败网络问题配置镜像加速器ES 内存不足JVM 堆配置过大修改 jvm.options 调低内存Redis 无法写入配置文件里 appendonly 关闭编辑 conf 开启 AOFAI 插件不工作版本不兼容检查 VS Code 版本以上这些都是我在实际搭建和后续使用过程中反复遇到过的每一条背后都有对应的排查经历并不是从文档里直接抄出来的。环境搭建最忌讳的是只看教程不亲手跑一遍很多问题只有实际操作时才会暴露。我个人在实际操作中的体会是Windows 上的 AI 开发环境搭建本身并不难难的是把各个组件的版本关系理清楚。Python 版本、JDK 版本、ES 版本、Docker 版本每一样都环环相扣建议你每一步都记录下来比如把安装的版本号、修改过的配置文件、设置过的环境变量都整理到一个文档里后续排查问题会轻松很多。最后再分享一个小技巧把 Windows Terminal 设为默认终端然后给它配置好 Git Bash、Ubuntu (WSL) 和 PowerShell 三个 profile日常开发时用快捷键切换体验非常接近 macOS 的 iTerm2。这套环境搭好之后后续在这个基础上加 Python 包、加 AI 模型、加新的本地服务都会顺畅很多。