企业官网建设流程全解析

装 AI 编程环境这件事，卡住大多数人的从来不是某一条命令，而是命令之间的先后顺序，以及每条命令背后默认了什么。我在 Windows 上反复装过十几遍这套东西：给同事的机器装、给自己的新硬盘装、在没有外网的机房里装。每一次翻车的原因都不一样，但失败的位置高度集中——无非是 PATH 顺序乱了、装成了 CPU 版的框架、或者插件指向了没启动的服务。这篇内容就是把整套 Windows AI 编程环境的搭建过程拆开讲清楚，从包管理器、终端、版本控制这些系统底座，一直讲到显卡驱动、本地模型运行时、Python 依赖治理和编辑器里的 AI 助手接入。不管你是刚拿到新电脑准备入门 AI 编程的新手，还是需要给团队批量配置开发环境的工程师，都能在这里找到可以直接照抄的步骤和判断依据。

1. 先把"环境"这个词拆开：Windows 上的 AI 编程环境到底分几层

很多人一说"搭环境"就直接去下 Python 安装包，装完发现还要装 Git、还要装编辑器插件、还要跑本地模型，一路补票。问题在于，这些组件之间是有依赖方向的：下层没弄对，上层怎么配置都是白费。所以动手之前，先花五分钟把层次关系想明白，后面能省下几个小时。

1.1 四层结构，以及每层坏掉时的典型症状

我习惯把它分成四层，每一层出问题时的表现差别很大，认准症状就能快速定位到层：

看这张表你会发现一个规律：越靠下的问题越"物理"，越难绕过；越靠上的问题越"配置"，改一个参数就能解决。新手最容易犯的错，是在最上层耗时间，却不知道真正的原因在最下层——比如补全一直乱写，其实是本地模型根本没加载成功，插件退回到了很小的兜底模型。

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\envs，conda 的 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\pkgs

envs_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。

判断兼容性的实操顺序：

1. 运行nvidia-smi，记下右上角的版本号；
2. 查你要装的框架官方安装页面，看它给出的安装命令后缀（比如cu124就代表 CUDA 12.4）；
3. 比较这两个数字，驱动支持的版本更高或相等就没问题；
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（预留开销）+ 上下文缓存

不同精度下每个参数占的字节数差别很大，这是决定能不能跑起来的关键：

那个 1.2 的系数是给激活值、框架开销预留的，实测下来比精确计算更省事。上下文缓存这一项容易被忽略：上下文窗口开得越大、并发越多，这部分占用越高，有时候能到几个 GB。所以如果你发现模型能加载但一开到长上下文就崩，问题大概率在这里。

3.4 离线与内网环境的模型搬运

企业内网或者没有外网的机器上，模型下载是最头疼的一步。我的做法是三步走：

第一步，在能联网的机器上把模型拉取到本地，找到实际的模型文件目录。第二步，把整个目录打包，用移动硬盘或者内网文件服务搬过去，注意保留目录结构，不要只拷单个文件。第三步，在目标机器上设置模型存储路径的环境变量，把包解压到那里，再启动服务验证。

验证环节必须做，不能只看服务起来了就算成功。用一个简单请求测试一下，看返回是否正常，同时观察加载时的显存占用是否符合前面估算的数值。如果显存占用异常低，很可能是加载失败后退回了某种降级模式。

注意：跨机器搬运模型文件时，一定要记录源机器上的文件校验值，搬完在目标机器上核对一遍。大文件在拷贝过程中损坏的概率不高但绝对不为零，一旦损坏，表现是加载到一半报错，排查起来非常费时间。

4. Python 依赖治理：把"装得上"变成"复现得出"

前三层解决的是"能不能用"，这一层解决的是"半年后还能不能用"。我在团队里见过太多次这样的情况：某个项目当初跑得好好的，几个月后换了台机器重新配环境，装出来的结果就是不一样，报错还各不相同。

4.1 conda 管解释器、pip 管包的边界在哪里

一条我觉得很有用的经验：用 conda 创建环境和安装带二进制的科学计算库，用 pip 安装纯 Python 包和框架本体。理由是这样能最大化利用 conda 的二进制依赖解析能力，同时避免 pip 装出来的版本和 conda 装的版本互相覆盖。

具体操作流程：

1. 明确 Python 版本再创建环境，不要用默认版本，指定成项目实际需要的版本；
2. 创建时就把常用的科学计算库一起装上，让 conda 统一解析依赖；
3. 激活环境后，用 pip 装框架本体和项目特有的包；
4. 全程不要在 base 环境里装任何项目依赖。

创建命令大致长这样：

conda create -n aienv python=3.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，一旦某个项目超过两周还在维护，立刻转成 pyproject。转换成本很低，收益是依赖边界清晰，别人拿走你的项目能一次装对。

不管用哪种，有一点必须坚持：依赖文件里要写版本范围，不要留空。numpy和numpy>=1.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] memory=16GB processors=8 swap=8GB localhostForwarding=true

memory建议设成物理内存的一半左右，processors不超过物理核心数，localhostForwarding打开后可以在 Windows 侧直接用本机地址访问子系统里的服务，省掉查 IP 的麻烦。改完配置要执行关闭命令再重启子系统才生效。

还有一个细节：子系统里的文件访问 Windows 侧目录会有明显性能损耗，反过来也一样。所以项目代码放在哪一侧，要根据你的主要编辑环境决定，不要两边来回跨。

6.2 容器工具的常见故障与离线安装思路

容器能把"环境"打包成一个镜像，是解决协作一致性的核心手段。在 Windows 上装容器工具，最常见的两类问题：

第一类是启动失败，原因是后台服务没运行或者资源没分配。检查顺序是：先确认子系统正常工作，再看容器工具的后台服务状态，最后看资源分配是否足够。资源不足时容器能启动但一跑重任务就崩，表现和内存泄漏很像，容易误判。

第二类是网络受限环境下拉不到镜像。应对思路有三种：使用内网镜像服务、把镜像导出成文件搬运、或者改用轻量镜像自己构建。第二种的流程是：在能联网的机器上拉取镜像，导出为归档文件，搬到目标机器后导入。归档文件通常比原始镜像小一些，但依然可能几个 GB，搬运时注意校验。

如果需要静默安装，容器工具的安装程序支持命令行参数，指定后端类型和接受许可协议后可以无人值守完成。这一步在做批量部署时很有用。

6.3 什么该进容器，什么不该

不是所有东西都适合塞进容器。我的判断标准是这样：

适合进容器的：需要特定系统版本的服务、依赖复杂且容易冲突的运行时、需要团队完全一致的构建环境、需要快速销毁重建的测试环境。

不适合进容器的：需要直接访问显卡的推理服务（虽然有方案，但配置复杂度和收益不成正比）、开发时的编辑器本体、日常的脚本工具、以及需要频繁读写大文件的数据处理任务。

一个实际的组合方案是：容器里跑依赖复杂的后端服务和数据库，本地直接跑模型推理服务，编辑器装在主机上，通过接口把两边连起来。这样既有环境一致性，又避开了显卡直通的麻烦。

注意：数据卷映射的路径写法在 Windows 和 Linux 下不同，配置错了容器会静默用一个空目录，表现是"数据不见了"但没有任何报错。写完配置后一定要进容器确认目录内容。

7. 排障速查：最容易卡住的那些点

环境搭建的问题，八成集中在几个固定位置。把下面这张表存下来，遇到问题时按症状查，比盲目搜索快得多。

7.1 症状与原因对照

7.2 三个最容易被忽略的细节

第一个是环境变量的生效范围。用命令行临时设置的变量只对当前会话有效，关掉终端就没了；用系统设置界面改的是持久变量，但已经打开的终端不会自动刷新。所以每次改完环境变量，务必重开终端，并且用一个echo命令确认值是对的。这个动作养成习惯后，能省掉大量"明明改了却没用"的困惑。

第二个是安装日志。包管理器和安装程序都会生成日志，位置通常在用户的临时目录下。装失败时先去看日志的最后几十行，比在搜索引擎里换关键词快得多。日志里的错误码是最有价值的信息。

第三个是环境快照。每完成一个阶段性配置，导出一份环境清单，记录装了哪些工具、什么版本、改了哪些配置。我用一个纯文本文件维护这份清单，放在项目根目录。重装系统或者换机器时，照着清单走一遍，一两个小时就能恢复。这份清单的价值，只有在你经历过一次硬盘故障之后才会真正体会到。

最后分享一个我自己一直在用的小技巧：新机器上先把所有配置写成一个可执行的脚本文件，参数改成幂等的（重复执行不报错）。这样下次换机器，跑一遍脚本，去喝杯咖啡回来环境就好了。脚本本身可能就只有几十行，但它把前面所有踩过的坑都固化下来了。