装 AI 编程环境这件事卡住大多数人的从来不是某一条命令而是命令之间的先后顺序以及每条命令背后默认了什么。我在 Windows 上反复装过十几遍这套东西给同事的机器装、给自己的新硬盘装、在没有外网的机房里装。每一次翻车的原因都不一样但失败的位置高度集中——无非是 PATH 顺序乱了、装成了 CPU 版的框架、或者插件指向了没启动的服务。这篇内容就是把整套 Windows AI 编程环境的搭建过程拆开讲清楚从包管理器、终端、版本控制这些系统底座一直讲到显卡驱动、本地模型运行时、Python 依赖治理和编辑器里的 AI 助手接入。不管你是刚拿到新电脑准备入门 AI 编程的新手还是需要给团队批量配置开发环境的工程师都能在这里找到可以直接照抄的步骤和判断依据。1. 先把环境这个词拆开Windows 上的 AI 编程环境到底分几层很多人一说搭环境就直接去下 Python 安装包装完发现还要装 Git、还要装编辑器插件、还要跑本地模型一路补票。问题在于这些组件之间是有依赖方向的下层没弄对上层怎么配置都是白费。所以动手之前先花五分钟把层次关系想明白后面能省下几个小时。1.1 四层结构以及每层坏掉时的典型症状我习惯把它分成四层每一层出问题时的表现差别很大认准症状就能快速定位到层层次常见组件出问题时的表现系统底座winget / Scoop、PowerShell 7、Git、Node.js命令行提示不是内部或外部命令脚本被策略拦截语言运行时Miniconda、Python 3.11、独立环境import 报错删掉又冒出别的版本包版本互相打架硬件与推理显卡驱动、运行库、本地模型服务推理速度慢得离谱或者直接报显存不足编辑器与助手VS Code、补全与对话类插件补全胡编插件提示连接失败代码上下文送不出去看这张表你会发现一个规律越靠下的问题越物理越难绕过越靠上的问题越配置改一个参数就能解决。新手最容易犯的错是在最上层耗时间却不知道真正的原因在最下层——比如补全一直乱写其实是本地模型根本没加载成功插件退回到了很小的兜底模型。1.2 我踩过的三个典型翻车现场第一个现场是 Python 版本地狱。很多教程让你直接在官网下载 Python 安装包一路下一步并且勾选Add Python to PATH。你按这个做完再去装 Miniconda此时系统里就有两套 Python 解释器PATH 里谁在前面完全取决于安装顺序。结果就是pip install装到了 A 环境你运行脚本用的是 B 环境报错信息还很客气地只写一句没有名为 xxx 的模块。这种问题不靠直觉只能靠where python和Get-Command python -All去看清楚。第二个现场更隐蔽装深度学习框架时用了默认源装完torch.cuda.is_available()返回False。代码能跑只是慢很多人就此以为我这机器性能就这样。实际上装的是 CPU 版本。判断方法很简单装完立刻跑一行验证而不是等训练脚本跑了半小时才回头怀疑。第三个现场出在插件侧。AI 编程助手配置里填了本机地址和端口但对应的本地服务压根没启动或者启动后换了端口。插件不会明确告诉你服务不存在它只会表现得很笨。所以任何涉及本地服务的配置都要养成先单独验证服务再验证插件的习惯。1.3 我的目录约定让环境、模型、代码三者互不打扰这一步看起来是小事但它决定了你半年后能不能顺利迁移到新硬盘。我的约定是这样环境统一放在非系统盘例如D:\Dev\envsconda 的 envs 目录直接指到这里模型文件单独一个目录例如D:\Dev\models因为本地模型文件动辄几 GB 到几十 GB混在系统盘里会让 C 盘迅速变红项目代码放D:\Dev\projects一个项目一个文件夹每个项目自带环境声明文件C 盘只保留系统、驱动和必须装在系统盘的工具。之所以强调把模型独立出来是因为本地推理工具默认会把模型放在用户目录下。等你 C 盘只剩几 GB 的时候再想迁移就要改环境变量、改配置、重新拉取麻烦程度远超一开始就规划好。这个坑我在一台 256GB 的笔记本上完整踩过一次最后不得不把整个用户目录下的模型缓存手动搬走。2. 系统底座包管理器、终端与版本控制的实际落位底座这层的目标是让后面所有工具的安装都可以用一行命令完成并且版本可查、可升级、可卸载。手工下载安装包点击下一步的方式装三个软件还行装三十个就一定会出乱子。2.1 winget 和 Scoop 的分工边界Windows 自带的 winget 现在已经足够好用绝大多数主流工具都能直接装winget install --id Git.Git -e --source winget winget install --id Microsoft.PowerShell -e winget install --id Microsoft.VisualStudioCode -e winget install --id OpenJS.NodeJS.LTS -e参数里-e表示精确匹配 ID加上它能避免装错同名软件--source winget是为了在网络环境里存在多个源时明确指定。这两个参数建议养成习惯尤其是公司电脑上装了一堆自建源的情况下。Scoop 的定位和 winget 略有不同它更适合装那些绿色、不需要管理员权限、不需要写注册表的命令行工具。比如你想装一堆小工具做数据处理Scoop 的体验会比 winget 顺滑。我的做法是系统级、需要写注册表的走 winget命令行小工具走 Scoop两者不冲突。要注意的是不要用两个管理器装同一个软件卸载时会互相残留。提示装完之后用winget list和自己手动装过的软件对一遍把重复的卸载掉尤其是 Git 和 Node.js 这两类最容易被重复安装。2.2 Miniconda 的正确装法与 PATH 陷阱AI 编程场景里我强烈建议用 Miniconda 而不是直接装 Python原因有三点它能同时管理多个解释器版本它能在环境里装非 Python 的二进制依赖它的环境隔离比 venv 更彻底。安装时有一个关键选择不要勾选Add Miniconda3 to my PATH environment variable。我知道这很反直觉几乎所有教程都在强调要加到 PATH。原因是 conda 有自己的一套激活机制靠conda activate切环境如果你把 base 环境硬塞进 PATH那么每次开终端都会默认进入 base而且其他工具调用的 Python 会莫名其妙变成 conda 的 base 环境。正确做法是装完之后手动初始化conda init powershell如果这条命令报执行策略错误先放开当前用户的策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这里用-Scope CurrentUser而不是改全局是为了不影响系统上其他用户的设置也不需要管理员权限。改完重开终端你应该能在提示符前面看到(base)。装完之后立刻改两件事把 envs 目录移到非系统盘以及配置镜像源。移动目录是通过修改.condarc实现的位置在用户目录下channels: - defaults default_channels: - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2 custom_channels: conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud envs_dirs: - D:\Dev\envs pkgs_dirs: - D:\Dev\pkgsenvs_dirs写在第一位是关键它决定了新建环境默认落在哪里。pkgs_dirs同样重要conda 的包缓存会越来越大放系统盘迟早出问题。这两项配置好之后后面所有conda create都不用再操心路径。2.3 Git、PowerShell Profile 与换行符统一Git 装完别急着用先把几条全局配置改掉这几条在 Windows 上几乎必改git config --global init.defaultBranch main git config --global core.autocrlf input git config --global core.quotepath false git config --global core.longpaths true git config --global user.name 你的名字 git config --global user.email 你的邮箱逐条解释一下为什么。init.defaultBranch是因为默认分支名现在普遍用 main不改的话每次新建仓库都要手动改一次。core.autocrlf input是最容易踩坑的一条如果设成true检出时会把换行符转成 CRLF某些脚本和配置文件在容器里运行时会因为多出来的回车符直接报错而且这种错误极难排查日志里只显示某个莫名其妙的语法错误。设成input表示提交时把 CRLF 转成 LF检出时不转换对跨平台协作最友好。core.longpaths解决的是 Windows 路径长度限制。Python 项目的依赖目录层级经常很深嵌套的 node_modules 或者虚拟环境路径很容易超过 260 个字符。这个配置能解决 Git 层面的问题但要彻底解决还需要在系统层面开启长路径支持通过组策略或者注册表中的LongPathsEnabled项。这个细节我建议顺手一起改掉否则某天拉取一个前端项目时会突然失败报错信息还特别含糊。PowerShell 的 Profile 是另一个值得投入五分钟的地方。用$PROFILE查看文件路径没有就新建。我在里面固定放三样东西常用别名、conda 初始化脚本由conda init自动写入、以及一个快速查看环境的函数。不要在里面放太多东西Profile 每次开终端都会执行加得越多终端启动越慢超过一两秒你就会开始烦躁。2.4 Node.js 与前端化 AI 工具链的前置条件这一条经常被忽略。现在的 AI 编程工具链里相当一部分工具是用 Node.js 写的编辑器插件、模型上下文协议相关的服务、各种本地小工具。你没有 Node.js很多工具装到一半就会失败而失败信息往往只显示一句找不到命令。装 LTS 版本就行不要追最新的实验版本。装完执行node -v和npm -v确认。如果打算同时维护多个前端项目再装一个包管理器做版本管理把全局包目录也挪到非系统盘npm config set prefix D:\Dev\npm-global改完记得把这个目录加到用户环境变量 PATH 里。这一步的收益是以后所有npm install -g的全局包都不会再往系统盘塞重装系统时损失最小。3. 显卡、驱动与本地推理运行时跑得起来和跑得快是两回事这一层是 AI 编程环境区别于普通编程环境的核心。很多人以为装了驱动就万事大吉实际上从驱动到能跑推理之间还有几个环节每个环节都可能出问题。3.1 先看驱动再看运行库版本对应关系怎么读第一步永远是运行nvidia-smi。这个命令输出的右上角会显示一个类似 CUDA Version: 12.4 的字样。这个数字不是你安装的 CUDA 版本而是当前驱动所能支持的最高 CUDA 版本。这个区别非常关键很多人在这一步就理解错了然后去下载对应版本的 CUDA Toolkit装完发现还是跑不起来。正确的理解方式是这样的框架比如深度学习库在编译时会绑定一个 CUDA 运行时版本只要驱动支持的最高版本不低于它就能正常跑。所以流程应该是先确定你要用的框架需要哪个 CUDA 版本再看驱动支不支持不支持就升级驱动而不是盲目安装一堆 Toolkit。判断兼容性的实操顺序运行nvidia-smi记下右上角的版本号查你要装的框架官方安装页面看它给出的安装命令后缀比如cu124就代表 CUDA 12.4比较这两个数字驱动支持的版本更高或相等就没问题如果不满足去官网更新驱动更新后重新运行nvidia-smi确认。在 Windows 上绝大多数情况下你不需要单独安装 CUDA Toolkit。框架的预编译包已经内置了所需的运行库单独装 Toolkit 反而可能引入版本冲突。只有在你需要自己编译带自定义算子的扩展时才需要完整的 Toolkit。这个认知能帮你省下几个 GB 的下载和一堆环境变量配置。3.2 本地模型运行时的两种形态命令行与桌面工具本地跑模型现在主要有两种形态选择取决于你的使用场景。第一种是命令行形态的服务安装简单、启动快、方便被其他程序调用。安装之后它会常驻在后台默认监听本机的一个端口提供兼容常见接口规范的 HTTP 服务。这意味着任何支持自定义接口地址的编辑器插件、脚本、程序都能直接连上不需要额外写适配代码。winget install --id Ollama.Ollama -e ollama pull qwen2.5-coder:7b ollama run qwen2.5-coder:7b第一次安装后建议立刻设置模型存储目录的环境变量指向你的非系统盘目录。这个变量必须在服务启动前就设置好服务启动后再改是无效的。设置完要重启一次终端让变量生效。第二种是桌面应用形态。它的优势是带图形界面能直观看到显存占用、推理速度、上下文长度这些指标适合用来做模型对比和参数调试。劣势是自动化集成不如命令行方便。我的建议是两个都装用桌面工具做模型选型和效果对比定下来之后用命令行服务做日常集成。3.3 显存够不够一个粗糙但实用的估算方法模型跑不动十次里有八次是显存不够但报错信息往往很不直观。与其反复试错不如动手前先估算一下。方法很简单记住一个粗略的公式显存占用 ≈ 参数量 × 每个参数的字节数 × 1.2预留开销 上下文缓存不同精度下每个参数占的字节数差别很大这是决定能不能跑起来的关键量化精度每参数字节7B 模型大致占用适用场景FP162 字节约 14 GB精度要求高显存充足INT81 字节约 7 GB平衡选择INT40.5 字节约 4 GB显存紧张日常补全够用那个 1.2 的系数是给激活值、框架开销预留的实测下来比精确计算更省事。上下文缓存这一项容易被忽略上下文窗口开得越大、并发越多这部分占用越高有时候能到几个 GB。所以如果你发现模型能加载但一开到长上下文就崩问题大概率在这里。3.4 离线与内网环境的模型搬运企业内网或者没有外网的机器上模型下载是最头疼的一步。我的做法是三步走第一步在能联网的机器上把模型拉取到本地找到实际的模型文件目录。第二步把整个目录打包用移动硬盘或者内网文件服务搬过去注意保留目录结构不要只拷单个文件。第三步在目标机器上设置模型存储路径的环境变量把包解压到那里再启动服务验证。验证环节必须做不能只看服务起来了就算成功。用一个简单请求测试一下看返回是否正常同时观察加载时的显存占用是否符合前面估算的数值。如果显存占用异常低很可能是加载失败后退回了某种降级模式。注意跨机器搬运模型文件时一定要记录源机器上的文件校验值搬完在目标机器上核对一遍。大文件在拷贝过程中损坏的概率不高但绝对不为零一旦损坏表现是加载到一半报错排查起来非常费时间。4. Python 依赖治理把装得上变成复现得出前三层解决的是能不能用这一层解决的是半年后还能不能用。我在团队里见过太多次这样的情况某个项目当初跑得好好的几个月后换了台机器重新配环境装出来的结果就是不一样报错还各不相同。4.1 conda 管解释器、pip 管包的边界在哪里一条我觉得很有用的经验用 conda 创建环境和安装带二进制的科学计算库用 pip 安装纯 Python 包和框架本体。理由是这样能最大化利用 conda 的二进制依赖解析能力同时避免 pip 装出来的版本和 conda 装的版本互相覆盖。具体操作流程明确 Python 版本再创建环境不要用默认版本指定成项目实际需要的版本创建时就把常用的科学计算库一起装上让 conda 统一解析依赖激活环境后用 pip 装框架本体和项目特有的包全程不要在 base 环境里装任何项目依赖。创建命令大致长这样conda create -n aienv python3.11 numpy pandas jupyter -y conda activate aienv很多人习惯conda create完就一路 pip这样也能跑但遇到需要编译的包时容易出问题。混用的原则不是不能混而是要有明确的先后和边界。4.2 镜像源、超时与重试让下载不再半路死掉pip 的默认源在某些网络环境下速度很不理想几个 GB 的框架装到 90% 断了是家常便饭。配置镜像源和超时是最基本的优化pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.timeout 120 pip config set global.retries 5超时设成 120 秒是因为大包下载时单个连接的间隔时间可能较长默认值容易误判断线。重试次数设 5 能兜住偶发的网络抖动。有一点要提醒镜像源和官方源不要混着用。有些人配了镜像源但装框架时又手动加-i参数指定另一个源导致同一个环境里的包来自不同源元数据不一致后续升级时可能出现版本解析失败。统一用一个源装不上再临时切换装完切回来。4.3 requirements 与 pyproject 两种打法的取舍这两种依赖声明方式各有适用场景我用一张表来对比维度requirements.txtpyproject.toml上手难度低一行一个包稍高需要理解分节版本约束表达支持但表达力有限表达力强支持复杂约束打包发布不适合标准做法项目脚本与元数据不支持支持适用场景脚本、实验、临时项目长期维护的工具与库我的实际做法是做实验和跑脚本用 requirements一旦某个项目超过两周还在维护立刻转成 pyproject。转换成本很低收益是依赖边界清晰别人拿走你的项目能一次装对。不管用哪种有一点必须坚持依赖文件里要写版本范围不要留空。numpy和numpy1.24,2.0在半年后的区别就是你能否快速复现当初的结果。4.4 深度学习框架的安装命令怎么拼这是最容易出错的一条命令写错了装成 CPU 版本代码照跑只是慢很难发现。原则是从框架官方安装页面生成命令不要凭记忆写。以常见的组合为例命令结构大致是这样pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124关键在最后的--index-url后缀cu124表示 CUDA 12.4 的预编译版本cpu表示 CPU 版本。这个后缀必须和你驱动支持的版本对应上。装完立刻验证三行代码import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))三行都应该有正常输出第二行必须是True。如果第二行是False先别急着怀疑驱动先确认装的是不是 CUDA 版本再检查环境变量里有没有干扰项。我遇到过一种情况机器上装了另一个工具它自带的运行库被加进了 PATH 前面导致框架加载了错误的动态库。这种情况通过where命令查看库文件的实际位置就能定位。4.5 锁版本的时机与导出方式依赖文件记录的是允许的范围实际装出来的是一组具体版本。这两者要分开管理。我的做法是开发阶段用范围声明验证通过后导出一份锁定文件作为快照。导出时要注意过滤掉本地路径和开发环境特有的包否则别人拿到这份文件在别的机器上装会失败。导出后过一遍文件内容把明显是本地路径的行删掉这个动作花不了一分钟但能避免很多沟通成本。环境锁定还有一个作用当你需要回滚到某个已知可用的状态时有一份确定的版本清单比对着日志猜快得多。我在调试框架兼容性问题时经常就是靠切换锁定文件快速定位到问题版本。5. 编辑器与 AI 编程助手的接入前面四层弄完你的机器已经具备跑 AI 程序的能力。但能跑 AI 程序和用 AI 来编程是两件事后者需要把助手接进编辑器的工作流里。5.1 补全、对话、Agent三类助手的定位差异现在的编辑器 AI 插件大致分三类混着用效果最好但一定要清楚各自的边界类型工作方式最适合的任务局限行内补全根据光标上下文续写写样板代码、补全重复结构对整体架构无判断力对话式你提问它回答解释代码、设计方案、写测试需要你提供上下文任务型自主读写多个文件批量重构、跨文件修改需要审阅容易改过头新手常见的误区是把所有任务都交给任务型助手结果它改了十个文件其中三个改错了回滚起来比手写还慢。比较合理的分配是写新代码用补全理解老代码用对话做重复性的批量修改用任务型并且每次改完都过一次版本差异。5.2 云端接口与本地模型的混编配置实际工作里云端模型和本地模型各有优势云端模型能力强本地模型响应快、不依赖网络、代码不出本机。合理的配置是两者同时接进来按任务切换。以常见的插件配置为例配置文件里通常会有一段模型列表每个模型声明提供方、模型名和接口地址。接本地服务时地址指向本机端口即可{ models: [ { title: 本地补全模型, provider: ollama, model: qwen2.5-coder:7b, apiBase: http://127.0.0.1:11434 } ], tabAutocompleteModel: { title: 本地补全, provider: ollama, model: qwen2.5-coder:7b } }配置完的验证顺序很重要先用命令行直接请求一次接口地址确认服务正常返回再在插件里点测试连接最后在真实代码文件里试一次补全。跳过第一步的人很容易在插件里折腾半小时最后发现是服务没起来。界面语言、快捷键、触发方式这些细节也值得花时间调。补全的延迟设成三百毫秒左右体验最好太短会频繁触发占用资源太长会打断思路。5.3 上下文与提示词从能补到补得对补全质量的决定因素往往不是模型本身而是你给了它什么上下文。几条实测有效的经验第一保持文件结构清晰。模型是靠周围代码推断意图的一个两千行的巨型文件里它很难判断当前该写什么拆成多个小文件补全准确率会明显提升。第二写清楚函数签名和类型标注。哪怕只写一行文档字符串说明参数的用途和边界条件补全出来的实现质量都会上一个台阶。类型标注对模型来说是非常强的信号。第三注释要写为什么而不是做什么。# 循环处理列表这种注释对模型没有任何帮助# 这里需要按时间倒序因为下游要求最新的在前才能给出真正的约束。第四长任务分步下指令。让助手一次性完成读代码、改接口、加测试、更新文档成功率远低于分四步做每一步你都检查一下。第五把项目的约定写进一个固定文件里比如编码规范、目录结构、命名习惯。很多插件会自动读取这类文件作为上下文等于每次对话都自动带上你的项目背景。提示如果你用的是本地小模型把上下文长度限制调小一点反而效果更好。上下文太长会稀释关键信息小模型处理长上下文的能力本来就有限。5.4 代码出域与忽略规则用云端模型意味着代码片段会离开你的机器。这件事本身没有问题前提是你清楚哪些内容不该发出去。我的做法是在项目根目录维护一份忽略规则把敏感配置、密钥文件、数据样本、内部文档都排除掉。编辑器读取这些规则后就不会把它们作为上下文发送。另外几条经验密钥不要写在代码里用环境变量或者本地配置文件配置文件本身加进忽略规则测试数据用脱敏后的样本如果项目有合规要求优先用本地模型处理全部代码相关任务云端模型只用来讨论通用的设计思路。检查方式也很简单在助手面板里看它当前引用了哪些文件如果列表里出现了不该出现的文件立刻去补充忽略规则。6. WSL2 与容器把环境一致性这件事做扎实到这一步单机环境已经能用了。但如果你需要和团队协作或者需要在多台机器之间切换光靠文档 手动安装是撑不住的必须引入容器和子系统。6.1 WSL2 的安装与资源限制在 Windows 上很多 AI 相关的工具链在 Linux 环境下更顺WSL2 是目前最省事的方案。安装过程已经很简化wsl --install -d Ubuntu wsl --set-default-version 2 wsl --update装完必须做的一件事是限制资源占用。默认配置下子系统会随着使用不断占用内存最后把主机内存吃光表现是整机变卡。解决办法是在用户目录下创建配置文件[wsl2] memory16GB processors8 swap8GB localhostForwardingtruememory建议设成物理内存的一半左右processors不超过物理核心数localhostForwarding打开后可以在 Windows 侧直接用本机地址访问子系统里的服务省掉查 IP 的麻烦。改完配置要执行关闭命令再重启子系统才生效。还有一个细节子系统里的文件访问 Windows 侧目录会有明显性能损耗反过来也一样。所以项目代码放在哪一侧要根据你的主要编辑环境决定不要两边来回跨。6.2 容器工具的常见故障与离线安装思路容器能把环境打包成一个镜像是解决协作一致性的核心手段。在 Windows 上装容器工具最常见的两类问题第一类是启动失败原因是后台服务没运行或者资源没分配。检查顺序是先确认子系统正常工作再看容器工具的后台服务状态最后看资源分配是否足够。资源不足时容器能启动但一跑重任务就崩表现和内存泄漏很像容易误判。第二类是网络受限环境下拉不到镜像。应对思路有三种使用内网镜像服务、把镜像导出成文件搬运、或者改用轻量镜像自己构建。第二种的流程是在能联网的机器上拉取镜像导出为归档文件搬到目标机器后导入。归档文件通常比原始镜像小一些但依然可能几个 GB搬运时注意校验。如果需要静默安装容器工具的安装程序支持命令行参数指定后端类型和接受许可协议后可以无人值守完成。这一步在做批量部署时很有用。6.3 什么该进容器什么不该不是所有东西都适合塞进容器。我的判断标准是这样适合进容器的需要特定系统版本的服务、依赖复杂且容易冲突的运行时、需要团队完全一致的构建环境、需要快速销毁重建的测试环境。不适合进容器的需要直接访问显卡的推理服务虽然有方案但配置复杂度和收益不成正比、开发时的编辑器本体、日常的脚本工具、以及需要频繁读写大文件的数据处理任务。一个实际的组合方案是容器里跑依赖复杂的后端服务和数据库本地直接跑模型推理服务编辑器装在主机上通过接口把两边连起来。这样既有环境一致性又避开了显卡直通的麻烦。注意数据卷映射的路径写法在 Windows 和 Linux 下不同配置错了容器会静默用一个空目录表现是数据不见了但没有任何报错。写完配置后一定要进容器确认目录内容。7. 排障速查最容易卡住的那些点环境搭建的问题八成集中在几个固定位置。把下面这张表存下来遇到问题时按症状查比盲目搜索快得多。7.1 症状与原因对照症状最可能的原因处理方向命令提示不是内部或外部命令PATH 未生效或装到了别的用户下重开终端用where查实际路径脚本执行被策略拦截执行策略限制放开当前用户策略为 RemoteSigned装完框架检测不到显卡装成了 CPU 版本重新用带 CUDA 后缀的命令安装推理速度异常慢显存不足退回内存或驱动版本过低看显存占用降低量化精度插件补全乱写本地服务未启动或端口不对先用命令行验证服务拉取项目失败路径过长或换行符问题开启长路径检查换行符配置子系统占用内存越来越高未限制资源上限写配置文件限制内存容器拉不到镜像网络受限内网镜像或归档搬运包安装到一半失败源不稳定或超时过短配置镜像源、加大超时和重试同一项目两台机器结果不同依赖版本未锁定导出锁定文件并核对7.2 三个最容易被忽略的细节第一个是环境变量的生效范围。用命令行临时设置的变量只对当前会话有效关掉终端就没了用系统设置界面改的是持久变量但已经打开的终端不会自动刷新。所以每次改完环境变量务必重开终端并且用一个echo命令确认值是对的。这个动作养成习惯后能省掉大量明明改了却没用的困惑。第二个是安装日志。包管理器和安装程序都会生成日志位置通常在用户的临时目录下。装失败时先去看日志的最后几十行比在搜索引擎里换关键词快得多。日志里的错误码是最有价值的信息。第三个是环境快照。每完成一个阶段性配置导出一份环境清单记录装了哪些工具、什么版本、改了哪些配置。我用一个纯文本文件维护这份清单放在项目根目录。重装系统或者换机器时照着清单走一遍一两个小时就能恢复。这份清单的价值只有在你经历过一次硬盘故障之后才会真正体会到。最后分享一个我自己一直在用的小技巧新机器上先把所有配置写成一个可执行的脚本文件参数改成幂等的重复执行不报错。这样下次换机器跑一遍脚本去喝杯咖啡回来环境就好了。脚本本身可能就只有几十行但它把前面所有踩过的坑都固化下来了。