YOLOv8新手入门｜半小时从0到1跑通目标检测 -字节曜-优质源码/游戏源码下载

前言

最近想入门目标检测，选了YOLOv8——毕竟是现在最主流的版本，官方文档也算友好，但作为纯新手，光看文档还是踩了不少细节坑。今天把“从装环境到跑出第一个检测结果”的全过程拆解得明明白白，主打一个“新手跟着做就能成”，先不抠复杂理论，咱先把代码跑起来、看到效果再说。

一、环境搭建：新手别贪新，稳最重要

YOLOv8依赖Python和几个核心库，版本不对会踩大坑，我先把每一步的操作和验证方法写清楚，按步骤来绝对不出错。

1. 第一步：确认Python版本（重中之重）

YOLOv8对Python版本有要求，太高的版本（比如3.11、3.12）会和依赖库不兼容，我亲测3.8、3.9、3.10这三个版本最稳，优先选3.9。

怎么查Python版本？打开电脑的终端（Windows叫命令提示符/PowerShell，Mac/Linux叫终端），输入：


python --version
# 或（部分电脑需要用python3）
python3 --version

回车后会显示版本号，比如“Python 3.9.18”就是合格的；如果显示3.11+，建议先装3.9版本（网上搜“Python3.9安装”，按系统步骤装就行，新手选“添加到PATH”，避免后续路径问题）。

2. 第二步：升级pip（避免安装库时出错）

pip是Python装库的工具，旧版本容易装错包、出现兼容性问题，先升级到最新版：


# Windows系统
python -m pip install --upgrade pip
# Mac/Linux系统
python3 -m pip install --upgrade pip

看到“Successfully upgraded pip”就说明升级成功了，耐心等几秒就行，过程很快。

3. 第三步：安装YOLOv8核心库ultralytics

ultralytics是官方维护的YOLOv8库，不用复杂配置，一行命令就能安装：


# Windows系统
pip install ultralytics
# Mac/Linux系统
pip3 install ultralytics

安装过程中会自动下载依赖的库（比如numpy、opencv、pillow等），不用手动干预。看到“Successfully installed ultralytics-xxx”（xxx是版本号），就说明核心库装好了。

4. 第四步：安装PyTorch（最容易踩坑的一步）

ultralytics必须依赖PyTorch才能运行，但直接用pip装可能会装到不匹配的版本，尤其是有显卡的同学，一定要按自己的系统和硬件选对命令，新手优先装CPU版，稳妥不出错。

先判断自己要不要装GPU版：如果你电脑是N卡（NVIDIA），且提前装了CUDA（新手如果没装CUDA，别折腾，先装CPU版，后续熟悉了再升级GPU）；AMD显卡或没有独立显卡的，直接装CPU版即可。

安装命令（复制对应版本，粘贴到终端执行）：

① CPU版（所有系统通用，新手首选）：


# Windows/Mac/Linux通用
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

② GPU版（仅NVIDIA显卡，需先装CUDA 11.8/12.1）：

去PyTorch官网（https://pytorch.org/get-started/locally/），按提示选择系统、CUDA版本，复制生成的命令。比如Windows系统+CUDA 11.8，命令如下：


pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

验证PyTorch是否装对（必做步骤）：装完后，在终端输入python（或python3）进入Python交互模式，依次输入两行代码：


import torch
print(torch.cuda.is_available())  # 有GPU且装对会显示True，CPU版显示False

如果没报错，就说明PyTorch装对了。输入exit()退出Python交互模式，进入下一步。

5. 最终验证：确认YOLOv8能正常导入

这一步能提前排查问题，避免后续写好代码白忙活。在终端输入python（或python3），输入：


from ultralytics import YOLO
print("YOLOv8环境搭建完成！")

没报错、能正常打印这句话，说明整个环境搭建完全没问题了，可以开始写代码跑demo了。

二、写6行代码，跑通第一个目标检测（全程不踩坑）

环境搭好，接下来就是最有成就感的环节——跑通第一个检测demo！我把代码逐行注释，新手照抄就行，连路径问题都帮你考虑到了。

1. 准备测试图片

① 找一张包含常见物体的图片（比如有猫、狗、人、杯子、汽车的图），别用带中文的图片名，会报错，重命名为test.jpg；

② 把图片放在一个容易找到的文件夹里，比如Windows的“桌面/YOLO_test”，Mac的“文稿/YOLO_test”，后续代码和图片放同一文件夹，不用记复杂路径。

2. 编写核心代码（逐行解释，新手能懂）

打开记事本（Windows）或文本编辑（Mac），复制下面的代码，保存为detect_test.py（同样别用中文文件名），和test.jpg放在同一个文件夹里：


# 1. 导入YOLO库（环境搭好才能正常导入，报错先查环境）
from ultralytics import YOLO

# 2. 加载YOLOv8预训练模型：选yolov8n（n代表nano，最轻量，运行最快，新手优先）
# 第一次运行会自动下载yolov8n.pt模型文件，耐心等几秒（网络差可手动下载）
model = YOLO('yolov8n.pt')

# 3. 执行目标检测：传入图片路径，conf=0.25代表置信度（低于25%的目标不识别，避免误检）
results = model('test.jpg', conf=0.25)

# 4. 保存检测后的图片（自动画彩色框，标注目标名称和置信度）
results[0].save('result.jpg')

# 5. 打印检测结果：清晰显示识别到的目标和置信度
print("检测完成！以下是识别到的目标：")
for box in results[0].boxes:
    # box.cls是目标类别编号，results[0].names是编号对应的类别名
    class_name = results[0].names[int(box.cls)]
    # box.conf是置信度，保留两位小数，更易读
    confidence = round(float(box.conf), 2)
    print(f"目标：{class_name}，置信度：{confidence}")

~~有点不准(bushi)~~

3. 运行代码（两种方式，选一种就行）

方式1：终端运行（推荐，新手易排查问题）

① 打开终端，切换到图片和代码所在的文件夹：

Windows系统（比如文件在桌面YOLO_test文件夹）：


cd Desktop/YOLO_test

Mac系统（比如文件在文稿YOLO_test文件夹）：


cd ~/Documents/YOLO_test

② 输入运行命令，执行代码：


# Windows系统
python detect_test.py
# Mac/Linux系统
python3 detect_test.py

方式2：用IDE运行（比如PyCharm、VS Code）

① 打开PyCharm/VS Code，导入存放代码和图片的文件夹；

② 右键点击detect_test.py文件，选择“Run”（运行），等待执行完成即可。

4. 查看检测结果（重点看这两个地方）

① 查看结果图片：文件夹里会多出result.jpg，打开后能看到图片上有彩色边框，边框旁标注了目标名称（比如cat、person、cup）和置信度，一目了然；

② 查看终端输出：终端会打印出识别到的目标和对应置信度，比如“目标：cat，置信度：0.92”，能清晰知道模型识别结果；

补充：如果没在文件夹根目录找到result.jpg，去runs/detect/predict目录找——这是YOLOv8默认的结果保存路径，第一次运行会自动生成这个文件夹，结果图一定在里面。

三、新手必看：我踩过的坑和解决方法

我第一次操作时，光环境搭建就耗了1小时，全是踩坑踩出来的经验，这几个坑新手大概率会遇到，提前记好解决方案：

1. 坑1：运行代码报“FileNotFoundError: test.jpg”

原因：图片路径错误，要么图片和代码不在同一文件夹，要么图片名写错（比如多打了空格、用了中文）。

解决：① 确认test.jpg和detect_test.py在同一文件夹；② 图片名必须是纯英文+后缀，无空格；③ 实在搞不定路径，就写绝对路径，比如Windows：model('C:/Users/你的用户名/Desktop/YOLO_test/test.jpg')，Mac：model('/Users/你的用户名/Documents/YOLO_test/test.jpg')。

2. 坑2：下载yolov8n.pt模型超时、失败

原因：网络问题，模型文件在国外服务器，国内网络下载容易卡顿超时。

解决：手动下载模型（网上搜“yolov8n.pt 官方下载”，从ultralytics官网或可信平台下载），把下载好的yolov8n.pt文件放到代码所在文件夹，代码会自动读取本地模型，不用再在线下载。

3. 坑3：导入YOLO时报“ImportError: Missing required dependencies ['torch']”

原因：PyTorch没装对，或版本不兼容，导致YOLO库无法调用。

解决：先卸载现有PyTorch，再重新安装。卸载命令：pip uninstall torch torchvision torchaudio，然后按前面的步骤重新装CPU版PyTorch，基本能解决。

4. 坑4：Mac运行报“OSError: dlopen(libtorch.dylib, 0x0006): Library not loaded”

原因：Mac系统Python环境混乱，库依赖路径不对。

解决：用Anaconda创建独立环境（新手搜“Anaconda安装教程”，很简单），创建Python3.9的环境后，在该环境下重新装ultralytics和PyTorch，就能避免路径冲突。

四、新手碎碎念

其实新手入门YOLOv8，最容易犯的错就是“追求新版本”“急于抠理论”——一开始我非要装Python3.12，结果各种兼容问题，换成3.9后瞬间顺畅；还总想着先搞懂“锚框”“特征提取”，越看越懵，反而打击积极性。

后来发现，先把代码跑起来、看到检测结果，有了成就感再回头补理论，效率会高很多。这篇教程主打“能跑就行”，把环境搭建、代码运行的每一步都拆碎，甚至把命令都写死，就是希望新手能少走弯路，快速get到目标检测的乐趣。

下一篇我会讲YOLOv8的拓展玩法——分割、姿态估计，其实就改一行代码的事，新手也能轻松上手，咱们下篇见。