企业官网建设流程全解析

1. 全身心投入YOLOv5之前，先把环境配置这一关吃透

翻开YOLOv5的学习笔记，真正劝退新手的往往不是模型结构有多复杂，而是第一步——环境配置。我在带学生和帮朋友排查问题的过程中发现，至少有一半的报错都发生在环境阶段：Python版本不对、PyTorch装不上、CUDA和显卡驱动对不上号，甚至有人因为一个conda源的问题折腾了一整晚。这篇文章就专门解决这些事。核心目标是：让一台从零开始的电脑，顺利跑起来YOLOv5的官方代码，并且能完成最基本的图片检测演示。

适合谁来读？完全零基础、第一次接触深度学习环境的小白；以前装过TensorFlow但没碰过PyTorch的人；以及被各种环境报错折磨到怀疑人生的朋友。如果你已经能熟练用YOLOv5训练模型，那这篇对你帮助不大，可以跳过。文章会从版本选择讲到实际操作步骤，最后给出常见的报错排查表，尽量做到每一步都有依据、每个参数都说得清为什么这么选。

在正式开始之前，我先说一个最重要的整体思路：环境配置的本质是版本匹配问题。Python、PyTorch、CUDA、显卡驱动、操作系统，这几者的版本必须互相兼容。很多人配置失败，不是因为操作不熟练，而是因为装了不匹配的版本组合。理解了这一点，后面遇到的每个报错你都能自己分析出原因。

2. YOLOv5环境配置的版本选型思路

2.1 为什么版本匹配比“装最新版”更重要

新手常见的思维是：什么新装什么。这放在普通软件上没问题，但放在深度学习框架上是会出大事的。PyTorch的不同版本对应不同的CUDA版本，而CUDA版本必须被显卡驱动支持。你装了一个特别新的PyTorch，它可能要求CUDA 12.x，但你的显卡驱动还是旧的，只能支持到CUDA 11.x，结果就是PyTorch检测不到GPU，只能老老实实跑CPU，速度慢到怀疑人生。

我建议的选型思路是这样的：反着来。先确定你的GPU支持什么驱动，再确定CUDA版本，再选择对应的PyTorch版本，最后确认Python版本。顺序不要颠倒。这个思路能帮你绕开大多数环境坑。

具体来说，以目前的YOLOv5官方代码为例，它要求的PyTorch版本是大于等于1.8的。但我不建议直接装太新的版本，除非你的显卡非常新。主流的选择是PyTorch 1.10到2.0之间的版本，配合CUDA 11.3或11.7。这套组合经过大量用户验证，稳定性高，报错少。

2.2 GPU版本和CPU版本怎么选

如果你手里没有NVIDIA显卡，或者显卡显存太小（小于2GB），那就老老实实用CPU版本。YOLOv5在CPU上也能跑，只是速度慢一些。做目标检测的推理演示，一张图片可能需要几秒到十几秒，但至少能跑通流程，学习原理足够用了。

如果你有NVIDIA显卡，建议显存不低于4GB，这样能比较从容地跑YOLOv5s这个小模型。显存只有2GB的话也可以尝试用CPU模式，或者把推理的图片尺寸调小。我用一张GTX 1050 Ti（4GB显存，很老的卡）跑YOLOv5s，速度完全能接受。

另外提一句，AMD显卡用户在新版本PyTorch里也有ROCm支持，但配置复杂度高一些，这里就不展开了。

2.3 操作系统与工具链的选择

Windows、Linux、macOS都能跑YOLOv5，但难度不一样。Windows用户最多，环境配置稍显繁琐，特别是CUDA和Visual Studio的依赖。Linux（Ubuntu）最省心，因为很多深度学习工具链都是先支持Linux的，报错也少。macOS如果是M系列芯片，需要装arm64版本的PyTorch，也能跑，但CUDA用不了，只能CPU。

如果你是纯粹为了学习，不想折腾系统，那Windows也可以。我下面写的步骤就以Windows为主，因为受众最广。如果你用的是Linux，思路完全一样，只是安装命令换成对应的包管理器。

3.1 下载并安装Anaconda，管理独立的Python环境

很多人喜欢直接给系统装Python，然后开始pip install。短期看挺方便，但时间长了必乱。项目A需要Python 3.8，项目B需要3.10，两个项目还各自依赖不同版本的包。如果全装在一个环境里，迟早会依赖冲突。所以我把Anaconda放在第一位，它就是用来做环境隔离的。

Anaconda的安装没什么特殊要求，从官网下载对应系统的安装包，一路默认安装即可。装的时候注意勾选“Add Anaconda to my PATH environment variable”，Windows上默认不勾，方便起见建议勾上。装完之后打开终端，输入conda --version能输出版本号就算成功。

考虑到国内网络问题，建议先配置清华或者阿里镜像源。命令行执行：

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

这样后续创建环境、安装包的速度会快很多。

3.2 创建虚拟环境，并确认Python版本

我创建虚拟环境时习惯给环境起一个有意义的名字。比如叫yolov5，后期一眼就知道这个环境是用来干什么的。命令行执行：

conda create -n yolov5 python=3.8

这里为什么选Python 3.8而不是3.11？因为PyTorch生态对Python 3.8的兼容性历史最悠久，很多第三方库对3.8支持稳定。3.10以上在一些老代码里可能会有小毛病。YOLOv5官方要求的Python版本是3.7到3.10，3.8属于比较保险的区间。

创建完成后，激活环境：

conda activate yolov5

你看到命令行前缀变成(yolov5)就说明成功进入虚拟环境了。后期想退出，执行conda deactivate即可。

3.3 安装PyTorch：GPU版和CPU版的命令区别

这是整个环境配置中最关键的一步。PyTorch的安装命令在官网首页有选择器（pytorch.org），可以根据你的操作系统、包管理器、CUDA版本来生成对应的命令。

如果你的电脑有NVIDIA GPU，而且确认了CUDA版本（比如11.7），命令类似这样：

pip install torch==1.13.1+cu117 torchvision==0.14.1+cu117 --extra-index-url https://download.pytorch.org/whl/cu117

这里有两个细节值得注意。第一，我没有直接用conda install torch，因为conda默认源的PyTorch版本可能较旧。第二，--extra-index-url参数指定了CUDA 11.7的下载源，这样装出来的PyTorch才自带对应的CUDA运行时。

如果是CPU版本，命令则简单许多：

pip install torch torchvision

装完之后不要急着装YOLOv5的依赖，先验证PyTorch到底能不能调用GPU。在命令行输入python进入交互模式，执行：

import torch print(torch.__version__) print(torch.cuda.is_available())

如果输出是True，恭喜，GPU环境正常。如果是False，那你需要回去检查驱动或者PyTorch的CUDA版本是否匹配，别急着往下走。

3.4 快速验证PyTorch与CUDA是否真正连通

这里多说一句，新手经常混淆两个概念：显卡驱动版本和CUDA版本。显卡驱动是底层的，它决定了你的GPU能被系统识别。CUDA是建立在驱动之上的计算平台。PyTorch安装时带的是CUDA运行时库，它需要底层驱动支持到对应的CUDA版本。

简单说，驱动越新，能支持的CUDA版本范围就越广。老驱动配上新CUDA，会报错或者直接检测不到GPU。如果你不确定，可以用nvidia-smi命令查看驱动信息，里面会显示Driver Version和CUDA Version。只要这个CUDA Version大于等于你PyTorch要求的版本，基本就稳了。

所以验证时如果我看到torch.cuda.is_available()返回True，我还会顺手打印一下设备名：

print(torch.cuda.get_device_name(0))

确认显示的确实是自己的显卡型号，而不是什么异常值。

4. 克隆YOLOv5源码并安装项目依赖

4.1 从GitHub拉取YOLOv5仓库

在YOLOv5环境里，激活虚拟环境后，cd到你想存放项目的目录（比如D:\codes），执行：

git clone https://github.com/ultralytics/yolov5.git cd yolov5

如果你的网络访问GitHub不稳定，也可以用一些镜像代理加速，不过我建议大家先直接试试原生速度，不行再找替代方案。克隆完成后，目录下会出现一系列文件，其中最重要的是requirements.txt和train.py、detect.py这些核心脚本。

4.2 requirements.txt里的依赖项与作用解析

YOLOv5的requirements.txt列出了所有需要的Python包，包括：

• matplotlib：用于绘制训练曲线和推理结果图
• numpy：数值计算基础库
• opencv-python：图像读取和预处理
• pillow：图像处理库
• PyYAML：用于解析yaml配置文件
• tqdm：进度条显示
• tensorboard：训练可视化
• torch、torchvision：深度学习框架

官方推荐直接执行如下命令安装全部依赖：

pip install -r requirements.txt

但我建议先打开这个文件看一眼，删掉或者注释掉已经有问题的行。尤其是有些版本冲突时，例如numpy版本过高或过低，会导致opencv无法正常import。我的习惯是装完之后逐个import验证，而不是等出错了才回头找。

4.3 安装过程中遇到的常见依赖版本冲突处理

依赖冲突最常见的一种就是numpy版本不匹配。比如YOLOv5要求numpy>=1.18.5，但你的opencv或matplotlib会要求较低的numpy版本。这时候要么升级numpy，要么降级opencv，具体看报错提示让你装哪个。别拿着提示直接pip install，先分析是谁在依赖谁。

还有一种情况是安装pycocotools时在Windows上失败。这个包需要Microsoft Visual C++构建工具。如果报错说明缺少VC++环境，就去安装Visual Studio Build Tools，勾选C++构建工具组件即可。macOS和Linux上相对省事，但Windows上确实容易碰到。

如果不想纠结这些依赖，直接装一个wheel文件也行：pip install pycocotools-wheels，然后再安装官方源里的pycocotools。这两个的顺序不能反，具体原因不展开，但实测有效。

5. 用一张猫猫狗狗图片检验整个环境是否真的可用

5.1 快速下载YOLOv5官方预训练权重

环境配置完成之后，最激动的时刻就是跑通第一个检测。YOLOv5官方给我们提供了预训练权重，不需要自己训练就能直接用。从GitHub或官方Release下载yolov5s.pt，把它放在yolov5目录下。也可以直接运行detect.py让它自动下载，但为了过程可控，建议手动下载。

如果你下载速度慢，可以去某些国内镜像站找找，文件名一致即可。权重文件不大，几十MB而已。

5.2 使用detect.py进行第一次推理

激活虚拟环境，在yolov5目录下执行：

python detect.py --weights yolov5s.pt --source data/images/bus.jpg

data/images/目录下自带两张测试图片，bus.jpg是其中一张。执行后，你会看到一行行日志输出，最后提示结果保存在runs/detect/exp目录下。打开那张带框的图片，model[ det ]检测出来的对象会被框住并标注类别和置信度。看到这个画面，说明你整个环境链路已经通了。

5.3 推理参数的简单调整：source、conf-thres、img-size

detect.py支持很多参数，最常用的是source，指定输入图片或视频路径；conf-thres，置信度阈值，默认0.25，如果你发现框太多误检，调高到0.5；img-size，图片缩放尺寸，默认640。这三个参数初期理解就够了。

举个例子，想检测一张自己手机里的图片，把它放在yolov5目录下，然后执行：

python detect.py --weights yolov5s.pt --source my_photo.jpg --conf-thres 0.4

系统会输出一个新的检测结果图片。注意路径中最好不要有中文和空格，否则偶尔会报错。

6. 环境配置的常见报错与解决方案速查

6.1 报错清单：ModuleNotFoundError、CUDA out of memory、torch.cuda.is_available()为False

我收集了新手阶段最高频的几种报错，做成了一张速查表，方便你对照排查。

6.2 经验总结：最容易被忽略的几个小坑

有几个坑几乎每个人都踩过，我单独拎出来强调一下。第一次是忘记激活环境，直接在base环境里pip install，结果装完发现项目识别不到包。第二是Windows路径反斜杠问题，Python里有时候要写成双反斜杠或者用正斜杠。第三是杀毒软件或防火墙拦截了GitHub下载，导致git clone失败，可以临时关掉重试。第四是安装完PyTorch后没有重启终端，某些环境变量没有生效，建议装完重要组件后重开一个终端窗口。

6.3 我个人的排查顺序，抄作业就行

当报错出现时，我建议按以下顺序排查，基本能解决80%的问题：

1. 检查是不是当前环境对不对，conda env list看激活状态。
2. 检查Python版本，python --version。
3. 检查PyTorch版本和GPU是否可用，python -c "import torch; print(torch.version, torch.cuda.is_available())"。
4. 检查CUDA版本是否与驱动匹配，nvidia-smi。
5. 检查每个依赖包的版本，pip list，对照requirements.txt看有没有明显冲突。

这套顺序看起来简单，但很有效。很多时候问题不在离奇的地方，就是环境激活错了或者版本太新了。

7. 环境配置完成之后该做什么

到了这一步，你手里的YOLOv5已经能跑通推理了。但环境配置只是学习的第一步，更核心的内容在后面。我建议接下来按照这几个方向继续深入：

第一，看懂YOLOv5的模型精读结构。读一遍models/yolov5s.yaml，搞清楚Backbone、Neck、Head每一层的作用。第二，用labelimg给自定义数据集打标签，然后训练自己的模型。这一步能让你真正体会到目标检测项目在做一件什么事情。第三，学会使用训练时的各种参数，比如batch-size、epochs、optimizer，搞清楚它们对结果的影响。第四，把YOLOv5集成到摄像头或者NVIDIA Jetson这类嵌入式设备上，你会发现推理场景更有趣。

记住，环境配置只是万里长征第一步，但也是最容易劝退人的一步。只要这一步走稳了，后面就不是问题了。我个人遇到新环境时，一直秉持一个原则：宁可多花一个小时把版本选型和依赖关系搞清楚，也不急着执行命令。因为改一个环境错误的时间成本远远大于初次规划的时间成本。

最后再分享一个小技巧：在正式跑YOLOv5之前，建议先执行一下python -m pip list > 环境快照.txt，把当前包列表保存下来。后面如果环境被弄乱了，对照这个快照就能快速恢复。这个小动作可能看起来不起眼，但在跑多个项目、来回切换环境的时候真的能救命。