企业官网建设流程全解析

都说Windows是深度学习的第一生产力，可真到了配环境这一步，生产力就变成了拆盲盒。尤其MMDetection，看着GitHub上给的安装命令一行行复制粘贴好像挺简单，但只要你用的是Windows，并且刚好需要安装指定版本，整套流程就会变得很魔幻。今天这篇教程就专门解决这个问题，目标非常明确：在Win10系统上，从零开始把MMDetection 2.19.0跑起来，配套安装mmcv-full 1.3.17，并且这套思路可以直接延展到往后更新的MMDetection版本。

先说清楚这篇文章适合谁看。你已经装了Python和CUDA，但是装MMDetection的时候各种报错装不进去；或者你刚接触目标检测框架，想在本地Windows环境跑一下训练和推理；再或者你是被网上那些“Linux一键安装”教程劝退的Windows用户，想找一个真正能把坑提前踩平的流程。这三种情况都可以直接照这篇教程操作。

另外说明一下，标题写的2.19.0是目前一个非常稳定的分支，但本文所有安装逻辑、版本选择策略、踩坑排查方法，对更新的MMDetection版本同样适用。因为重点不是让你背命令，而是把“版本对应关系”和“安装原理”搞清楚，只要这两点通了，后面升级版本就是换个数字的事。

1. 整体安装思路与版本规划

1.1 为什么Windows装MMDetection容易翻车

先别急着敲命令，换个角度想清楚一个问题：MMDetection不是一个独立软件，而是一个依赖链条很长的框架。它底层是PyTorch，PyTorch依赖CUDA，而MMDetection的核心组件都要通过mmcv-full和CUDA算子打交道。这条链上任何一环的版本对不上，结果就是运行时报错或者import失败。

Windows系统之所以比Linux更容易翻车，主要因为三点：

第一，第三方库的预编译wheel包发布不全。很多工具链作者默认用户用Linux，Windows版本的wheel要么没有，要么版本滞后。mmcv-full就是个典型，它的Windows wheel只发布到特定版本号，想安装比较新的版本就只能本地源码编译，而源码编译对Visual Studio工具链有硬性要求。

第二，路径和系统环境差异。Windows下CUDA的安装位置、Python解释器的路径、conda环境的激活方式，都跟Linux不一样。很多教程是Linux用户写的，默认路径都是/usr/local/cuda，Windows用户照着操作自然找不到文件。

第三，mmdetection的源码在Windows上偶尔会触发一些编译行为。某些算子在Windows环境下的编译方式比Linux更严格，动不动就抛fatal error C1083这类问题，很多新手看到这个就直接劝退了。

1.2 版本对应关系：这一步决定后面是否顺利

MMDetection、mmcv-full、PyTorch、CUDA这四者之间有一套严格的版本对应关系。不能说“我装最新版PyTorch就行”，也不能说“mmcv越新越好”。选错了，后面无论如何都跑不起来。

MMDetection 2.19.0对应的官方要求是：Python 3.6到3.9之间，PyTorch 1.5以上，mmcv-full版本需不低于1.2.4。但实际踩下来的结论是，pytorch在1.8到1.10之间会省心很多，我这篇文章推荐PyTorch 1.8.2 + CUDA 10.2这个组合，理由后面详说。mmcv-full则强烈建议安装1.3.17，因为这是官方为2.19.0推荐并测试过的最稳版本。

提示：MMDetection每个版本的release页面上都会写明对应的mmcv-full版本范围。装任何新版本之前，第一件事不是去搜教程，而是去GitHub看release notes，里面写着官方测过的mmcv版本。照着官方推荐装，大概率不会出大问题；自己随意组合，就是在为难自己。

1.3 推荐的安装组合与完整流程概览

结合实际操作经验，我推荐的组合是：Python 3.8 + PyTorch 1.8.2 + CUDA 10.2 + mmcv-full 1.3.17 + MMDetection 2.19.0。

选这个组合的原因有三个。Python 3.8是目前MMDetection生态兼容性最好的版本，3.9能用但没3.8稳，3.7以下的很多新库都不能装。PyTorch 1.8.2这个版本在所有Windows环境下的wheel包都非常完整，不需要本地编译，安装起来速度快而且不会出幺蛾子。CUDA 10.2则是当年PyTorch官方支持最成熟的版本，跟mmcv-full 1.3.17的匹配度最好。

完整流程分四步走：

1. 准备基础环境：Python、CUDA、Visual Studio工具链
2. 创建conda虚拟环境并安装PyTorch
3. 通过官方预编译wheel安装mmcv-full
4. 安装MMDetection并进行验证测试

这个顺序是强制的，基础环境没搞定，后面的步骤就是空中楼阁。下面按顺序一步步说清楚。

2. 安装前的环境准备与检查

2.1 Python与Conda环境准备

Python版本我上面说了，直接选3.8就行。如果你电脑上已经装了其他版本的Python也没关系，后续操作都在conda虚拟环境里进行，不会干扰你现有的环境。

这里强烈建议使用conda来管理环境，不管你用的是Anaconda还是Miniconda都行，如果电脑上啥也没有，直接装Miniconda，体量小而且够用。安装conda后，打开Anaconda Prompt或者普通的命令行窗口，先确认conda命令可用：

conda --version

然后创建独立的环境。这一步不要嫌麻烦，独立环境能保证你的项目依赖不跟其他项目互相污染，后面排查问题也方便很多：

conda create -n openmmlab python=3.8 conda activate openmmlab

激活之后，后续所有安装命令都在这同一个命令行窗口里执行，不要中途关掉或者换窗口，否则环境会丢，这是新手最容易忽略的细节。

2.2 CUDA与显卡驱动检查

很多人搞混一个概念：显卡驱动和CUDA Toolkit不是一回事。驱动是显卡运行的底层支撑，CUDA Toolkit是基于驱动之上提供的并行计算开发环境。检查驱动能不能支持CUDA，看的是驱动版本；而PyTorch要调用计算资源，本质上用的是CUDA Toolkit通过conda或pip装下来的那套库文件。

在命令行输入：

nvidia-smi

如果正常输出了显卡信息，说明驱动没问题。右上角的CUDA Version: 10.2或11.x之类的字样，表示你的驱动最高能支持的CUDA版本。比如驱动支持到CUDA 11.4，那么装CUDA 10.2的PyTorch和mmcv完全没问题，向下兼容的。

有些教程会教你额外单独安装一个CUDA Toolkit，但如果你选择PyTorch 1.8.2+cudatoolkit 10.2这个组合，完全不需要额外装CUDA Toolkit。因为conda会自动帮你在环境里装好cudatoolkit，整套运行时依赖是跟着PyTorch走的。

2.3 Visual Studio Build Tools：绕不开的Windows编译环境

这一节是Windows专属的重灾区，无数人在这里功亏一篑。

mmcv-full 1.3.17在Windows下的官方wheel只有特定版本，我推荐安装的这个版本能直接用预编译wheel。但问题是，Python轮子在加载扩展模块时，或者后续你自己安装其他OpenMMLab系列组件时，系统可能会触发本地源码编译。没有C++编译环境，就会报找不到cl.exe或者C1083之类的错误。

标准解决办法是安装Visual Studio Build Tools，不需要装完整的Visual Studio IDE，那个太占空间。去微软官网下载Visual Studio Build Tools安装器，运行时选择“使用C++的桌面开发”这一项工作负载，右侧默认勾选的组件保持不动，再额外勾选最新版Windows 10 SDK。安装时间会比较长，建议找个随时能联网的时间段来装。

注意：安装完Visual Studio Build Tools之后，需要重启一次电脑，或者至少重启命令行窗口，环境变量才能生效。没有这一步，后面如果触发编译操作，系统还是找不到编译器。

2.4 Git的安装与配置

MMDetection是通过pip安装的，但官方源码通常从GitHub拉取。虽然预编译wheel不强制要求Git，但后续下载demo推理用的权重文件、克隆官方示例仓库都离不开它。

去Git官网装Windows版，安装时一路默认即可。安装完验证一下：

git --version

到这里，基础环境就全部就绪了。接下来进入真正的安装环节。

3. 安装PyTorch：整个依赖链条的地基

3.1 PyTorch版本选择与CUDA匹配

PyTorch版本选择是整个安装流程中最关键的一步。你不能随便装新版，因为mmcv-full 1.3.17对PyTorch版本有明确的兼容范围要求。

直接给出结论：PyTorch 1.8.2加CUDA 10.2版是mmcv-full 1.3.17的最佳搭档。

这个结论怎么来的？第一，需要查阅当时mmcv-full官方文档，里面列出了PyTorch 1.3到1.8是经过测试的稳定范围；第二，PyTorch 1.8.2是1.x系列里最成熟稳定的一个patch版本，安装包完整，Windows下的wheel分发做得最广；第三，CUDA 10.2作为conda包直接安装，不需要系统级权限，对个人开发机最友好。

3.2 使用官方conda命令安装

在之前创建并激活的openmmlab环境中，输入以下命令：

conda install pytorch==1.8.2 torchvision==0.9.2 torchaudio==0.8.2 cudatoolkit=10.2 -c pytorch

这里需要注意一个细节：torchvision的版本必须和pytorch对应。PyTorch 1.8.2对应torchvision 0.9.2，这是官方固定匹配的版本对，不能随意换。换错了虽然Python包能装进去，但运行时会报一堆版本不匹配的警告，严重时还会直接报错。

安装完成后，验证PyTorch是否正常、CUDA是否可用：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

如果输出1.8.2加上True，说明PyTorch和CUDA全部就绪。这里有个常见问题值得说一下：很多人明明显卡是NVIDIA的，但torch.cuda.is_available()返回False。这种问题八成是cudatoolkit没装全，或者conda channels的优先级设置导致装成了CPU版。检查方式很简单，再次运行上面的命令时看版本号后面有没有+cu102后缀，如果是+cpu就说明装错了源。

3.3 踩坑提示：不要用最新版本PyTorch

有人会问，我直接装最新的PyTorch 2.x不行吗？在MMDetection 2.19.0这个框架版本下，真的不建议。

原因是MMDetection 2.19.0内部的很多算子实现是基于旧版PyTorch API写的，PyTorch 2.x改了很多内部接口。虽然OpenMMLab团队后来推出了适配新版PyTorch的MMDetection 3.x，但在2.19.0这个版本上，强行配新PyTorch只会带来无谓的兼容性麻烦。既然目的是跑起2.19.0，就乖乖用与之匹配的PyTorch 1.8.2，这是最省时省力的教科书式组合。

4. 安装mmcv-full：最核心也最折磨人的一环

4.1 为什么必须装mmcv-full而不是mmcv

先区分一个概念。MMDetection的底层依赖于mmcv，而mmcv分为两个发行版：mmcv和mmcv-full。前者是一个精简版，只包含基础模块，不包含CUDA算子；后者包含所有CUDA算子，目标检测、实例分割这些核心功能全部依赖这些算子。

直接说结论：装MMDetection必须装mmcv-full。只装mmcv的话，等import MMDetection的时候就会报错ModuleNotFoundError: mmcv._ext，这个错误出现的频率极高，基本属于每个新手都会踩的坑。

4.2 直接使用预编译wheel：Windows用户的最佳路径

Windows用户装mmcv-full有两个选择：源码编译或者预编译wheel。源码编译需要配好Visual Studio环境后自行运行setup.py，过程漫长不说，还经常出现各种莫名其妙的编译错误，实际体验非常糟糕。预编译wheel则是官方直接提供编译好的安装包，一条pip命令直接装完，省时省力。

mmcv-full的预编译wheel在官方文档里可以找到对应的下载链接。不同版本、不同Python、不同CUDA版本都有对应的不同链接，格式通常是：

https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html

需要注意一个小坑：wheel下载页面上的索引目录结构是cu102/torch1.8.0，虽然需要安装的是PyTorch 1.8.2，但当年mmcv官方编译时基于的是1.8.0构建，这个版本范围内wheel包是互相兼容的，直接用即可。

选定对应目录后，在环境里执行：

pip install mmcv-full==1.3.17 -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html

这里的-f参数指定了额外的wheel搜索地址，pip会在官方PyPI之外自动去这个页面上寻找对应版本号的wheel包。只要版本号匹配，就会直接下载并安装预编译好的安装包，不需要本地做任何编译。

4.3 源码编译方案与失败原因分析

那万一你需要的mmcv-full版本在官方wheel页面找不到怎么办？比如某些更新版本的mmcv-full并没有提供Windows预编译包。这时候就得走源码编译的路线了。

源码编译的前提条件在前面已经准备好，就是Visual Studio Build Tools。接着从GitHub拉取mmcv源码，在对应版本tag上直接执行安装：

git clone -b v1.3.17 https://github.com/open-mmlab/mmcv.git cd mmcv pip install -e .

但实操过程中，源码编译会绕不开两个经典问题。一是ninja构建工具在某些情况下会跟Visual Studio的编译器冲突，报出ninja: error: loading 'build.ninja'这一类问题；二是某些算子的编译特别吃内存和显存，编译过程中卡死或者直接报killed的都有。Windows用户如果真走到这一步，建议优先检查MSVC环境变量是否生效，并且关闭杀毒软件对构建目录的实时防护，能显著降低编译失败概率。

不过再次强调，1.3.17这个版本有官方预编译wheel，没必要自讨苦吃走编译路线。

4.4 验证mmcv-full是否安装成功

安装完成后，运行下面这段验证代码，用get_arch这个接口检查CUDA架构信息，顺便验证_ext模块是否存在：

python -c "import mmcv; from mmcv.ops import get_compiling_cuda_version, get_compiler_version; print(mmcv.__version__); print(get_compiling_cuda_version()); print(get_compiler_version())"

如果输出类似：

1.3.17 10.2 MSVC 19.xx

说明mmcv-full安装成功，CUDA算子和编译器信息都正常。如果报错ModuleNotFoundError: No module named 'mmcv._ext'，说明装成了精简版mmcv，需要重装mmcv-full。

5. 安装MMDetection 2.19.0与验证测试

5.1 使用pip直接安装

mmcv-full搞定之后，MMDetection的安装就变得很简单了。在同一个conda环境里执行：

pip install mmdet==2.19.0

pip会自动拉取依赖并安装，常用的opencv-python、matplotlib、terminaltables等依赖包会自动一并装好。整个安装过程一般不会报错，如果报错，多数是因为网络问题，换国内镜像源重试即可：

pip install mmdet==2.19.0 -i https://pypi.tuna.tsinghua.edu.cn/simple

5.2 源码安装方式与适用场景

如果你不满足于简单调用API，想改源码或者看内部实现细节，可以选择源码安装：

git clone -b v2.19.0 https://github.com/open-mmlab/mmdetection.git cd mmdetection pip install -e .

源码安装的好处是mmdetection目录下所有.py文件直接可见可改，改完立即生效，非常适合深度学习和目标检测的学习者来研究框架内部机制。缺点是目录最好不要随便移动位置，因为-e模式生成的egg-link文件指向的路径变了，import就会失败。

5.3 快速验证：能不能跑通一个推理Demo

装完之后先做基础验证，检查版本统一性：

python -c "import mmdet; print(mmdet.__version__)"

输出2.19.0就说明MMDetection安装成功。但这只是第一步，真正检验安装质量的方式是跑一个完整的推理Demo。从MMDetection官网下载一个faster_rcnn的预训练权重文件，放到一个项目目录里，然后写个脚本加载模型并对一张测试图进行推理。只要能顺利输出检测框结果，整条安装链条才算真正打通。

这里贴一个快速验证的脚本核心代码：

from mmdet.apis import init_detector, inference_detector config_file = 'configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py' checkpoint_file = 'faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth' model = init_detector(config_file, checkpoint_file, device='cuda:0') result = inference_detector(model, 'test.jpg') model.show_result('test.jpg', result, out_file='output.jpg')

第一次跑推理时，程序会自动下载对应的config文件或者初始化一些缓存，时间可能会久一点，耐心等就行。如果这一步能顺利跑出结果，整个安装流程就算完美收官了。

6. 高频报错与解决方案速查

6.1 环境配置类的常见报错

6.2 安装过程类的经典报错

6.3 排查工具与调试技巧

遇到问题先别慌，有几个通用排查套路值得养成习惯。

第一，分清报错发生在import阶段还是运行阶段。import torch就报错，说明PyTorch本身有问题；import mmcv报错，问题在mmcv相关依赖；from mmdet.apis import init_detector报错，多半是MMDetection依赖不完整。逐层向上排查，效率高得多。

第二，检查conda环境是否激活成功。这是很多人忽略的低级错误：命令行里(openmmlab)前缀没出现，所有包都装到了base环境，导致各种import不到。每次打开新窗口第一件事就是确认环境前缀。

第三，用pip list查看已安装版本，确认所有关键包的版本号完全匹配目标组合。一个命令能解决很多怀疑人生的时刻：

pip list | findstr /i "torch mmcv mmdet"

7. 新版本MMDetection的安装适配经验

7.1 版本升级的核心逻辑

文章标题里说了，这套方法适用于最新版本MMDetection。其实这句话的底层逻辑很简单：无论MMDetection版本怎么更新，它的安装套路都是固定的——先装PyTorch，再装对应版本的mmcv-full，最后装MMDetection本体。变的只是具体版本号组合。

比如你想装MMDetection 2.25.0，那就要去它的release页面查看对应的mmcv-full版本要求，再看mmcv-full需要哪个范围的PyTorch，最后反推conda安装命令里的版本号。版本对应关系永远是自上而下的：框架 -> 底层库 -> 深度学习框架 -> CUDA。

实际动手时，最高效的办法是先看MMDetection官方文档里的installation页面，上面会列出每个分支版本推荐的mmcv-full版本组合表格，照着选就行。

7.2 从2.x升级到3.x的注意事项

如果你装好了2.19.0之后想更进一步试试MMDetection 3.x，这里提前提醒三个区别：

第一，mmcv-full这个包名在3.x生态里已经废弃了，统一改名为mmcv，且不再区分精简版和完整版，安装逻辑变成了pip install mmcv>=2.0.0；第二，PyTorch最低版本要求提高了，官方推荐最低PyTorch 1.8以上，但实际测试下来1.11起步会更稳；第三，MMDetection 3.x的配置文件格式做了大规模重写，直接用2.x的配置是跑不起来的。

不过万变不离其宗，先把2.19.0这套流程吃透，理解版本对应关系的内在逻辑，未来升级任何新版本都只是查文档、改版本号、重装一遍的问题，不会再被折腾得焦头烂额。

8. 写在最后的实操体会

这套环境我前后踩了不下三轮，从一开始在Linux上装得顺风顺水，到转战Windows之后被各种编译问题捶打，再到后来把每个报错都整理成表格、总结成规律，整个过程印象太深了。如果你现在正卡在某一步，我的建议是别在报错信息上死磕太久，停一下，重新捋一遍版本链条，往往问题就出在某个版本的匹配关系上。

实际操作中还有一个小技巧值得分享，在你所有安装命令都成功执行之后，建议把整个环境打包记录一下，方便以后快速重建。用conda导出环境配置清单，不时看一下，对自己装过什么心里有数：

conda env export > environment.yaml

后续如果想在另一台电脑上复现这套环境，不需要再一个个手动装包，直接一条命令重建，爽快得很。这种操作习惯比任何安装教程都更能帮你节省时间。