以下是 C# 上位机 + YOLOv8 零基础入门的最简洁、完整、可直接复制运行的实战指南（2025 年底最新推荐方案）。目标是让你在 1 小时内 跑通第一个实时目标检测 demo。

一、最简技术选型（新手友好）

总共只需要 3 个 NuGet 包，非常干净。

二、环境搭建（5 分钟一步到位）

1. 安装 .NET 8 SDK
   官网下载：https://dotnet.microsoft.com/download/dotnet/8.0
   或命令行（推荐）：

   winget install Microsoft.DotNet.SDK.8
   

2. 创建 WinForms 项目

   dotnet new winforms -o YoloDemo
   cd YoloDemo
   

3. 安装依赖（最少 3 个）

   dotnet add package Microsoft.ML.OnnxRuntime
   dotnet add package OpenCvSharp4
   dotnet add package OpenCvSharp4.runtime.win   # Windows 用户用这个
   

   Linux 部署时把最后一行换成：

   dotnet add package OpenCvSharp4.runtime.ubuntu.22.04-x64
   

4. 下载 YOLOv8n.onnx 模型（int8 版推荐）

   • 地址：https://github.com/ultralytics/assets/releases/download/v8.3.0/yolov8n.onnx
   • 放项目根目录（或新建 models 文件夹）

三、完整最小 Demo 代码（MainForm.cs）

using Microsoft.ML.OnnxRuntime;
using Microsoft.ML.OnnxRuntime.Tensors;
using OpenCvSharp;
using System;
using System.Collections.Generic;
using System.Windows.Forms;

namespace YoloDemo
{
    public partial class MainForm : Form
    {
        private VideoCapture cap;
        private InferenceSession session;
        private const int InputSize = 640;
        private readonly Timer timer = new() { Interval = 100 }; // 10fps

        // COCO 80 类（部分示例，可替换为自定义类别）
        private readonly string[] classNames = {
            "person", "bicycle", "car", "motorcycle", "airplane", "bus", "train", "truck", "boat",
            "traffic light", "fire hydrant", "stop sign", "parking meter", "bench", "bird", "cat", "dog",
            "horse", "sheep", "cow", "elephant", "bear", "zebra", "giraffe", "backpack", "umbrella", "handbag",
            "tie", "suitcase", "frisbee", "skis", "snowboard", "sports ball", "kite", "baseball bat",
            "baseball glove", "skateboard", "surfboard", "tennis racket", "bottle", "wine glass", "cup",
            "fork", "knife", "spoon", "bowl", "banana", "apple", "sandwich", "orange", "broccoli", "carrot",
            "hot dog", "pizza", "donut", "cake", "chair", "couch", "potted plant", "bed", "dining table",
            "toilet", "tv", "laptop", "mouse", "remote", "keyboard", "cell phone", "microwave", "oven",
            "toaster", "sink", "refrigerator", "book", "clock", "vase", "scissors", "teddy bear", "hair drier",
            "toothbrush"
        };

        public MainForm()
        {
            InitializeComponent();
            InitCamera();
            InitYolo();
            timer.Tick += async (s, e) => await ProcessFrameAsync();
            timer.Start();
        }

        private void InitCamera()
        {
            cap = new VideoCapture(0, VideoCaptureAPIs.DSHOW);
            if (!cap.IsOpened())
            {
                MessageBox.Show("无法打开摄像头，请检查索引或驱动");
                Close();
            }
        }

        private void InitYolo()
        {
            try
            {
                var opt = new SessionOptions { IntraOpNumThreads = 2 };
                session = new InferenceSession("yolov8n.onnx", opt);
            }
            catch (Exception ex)
            {
                MessageBox.Show("模型加载失败：\n" + ex.Message);
                Close();
            }
        }

        private async Task ProcessFrameAsync()
        {
            using var frame = new Mat();
            if (!cap.Read(frame)) return;

            // 异步推理
            var detections = await Task.Run(() => Detect(frame));

            // UI 更新（跨线程安全）
            BeginInvoke(() =>
            {
                using var annotated = DrawDetections(frame, detections);
                pictureBox1.Image?.Dispose();
                pictureBox1.Image = annotated.ToBitmap();
                lblStatus.Text = detections.Count > 0 ? $"检测到 {detections.Count} 个目标" : "无目标";
            });
        }

        private List<Detection> Detect(Mat frame)
        {
            using var resized = frame.Resize(new Size(InputSize, InputSize));
            using var blob = Cv2.Dnn.BlobFromImage(resized, 1/255.0, new Size(InputSize, InputSize), swapRB: true);

            var tensor = new DenseTensor<float>(blob.GetData<float>(), [1, 3, InputSize, InputSize]);
            using var inputs = new[] { NamedOnnxValue.CreateFromTensor("images", tensor) };

            using var results = session.Run(inputs);
            return PostProcess(results[0].AsTensor<float>(), frame.Width, frame.Height);
        }

        private List<Detection> PostProcess(Tensor<float> output, int w, int h)
        {
            var list = new List<Detection>();
            int stride = 4 + classNames.Length;

            for (int i = 0; i < output.Dimensions[1]; i++)
            {
                float conf = output[0, i, 4];
                if (conf < 0.45f) continue;

                int bestCls = 0;
                float maxCls = 0f;
                for (int c = 0; c < classNames.Length; c++)
                {
                    float v = output[0, i, 5 + c];
                    if (v > maxCls) { maxCls = v; bestCls = c; }
                }

                float finalConf = conf * maxCls;
                if (finalConf < 0.45f) continue;

                float cx = output[0, i, 0] * w;
                float cy = output[0, i, 1] * h;
                float ww = output[0, i, 2] * w;
                float hh = output[0, i, 3] * h;

                float x = cx - ww / 2;
                float y = cy - hh / 2;

                list.Add(new Detection(
                    new Rect((int)x, (int)y, (int)ww, (int)hh),
                    finalConf,
                    classNames[bestCls]
                ));
            }

            // 简单 NMS
            list.Sort((a, b) => b.Conf.CompareTo(a.Conf));
            for (int i = 0; i < list.Count; i++)
                for (int j = list.Count - 1; j > i; j--)
                    if (IoU(list[i].Box, list[j].Box) > 0.45f)
                        list.RemoveAt(j);

            return list;
        }

        private static float IoU(Rect a, Rect b)
        {
            float inter = Math.Max(0, Math.Min(a.Right, b.Right) - Math.Max(a.Left, b.Left)) *
                          Math.Max(0, Math.Min(a.Bottom, b.Bottom) - Math.Max(a.Top, b.Top));
            return inter / (a.Width * a.Height + b.Width * b.Height - inter);
        }

        private Mat DrawDetections(Mat frame, List<Detection> detections)
        {
            var img = frame.Clone();
            foreach (var d in detections)
            {
                Cv2.Rectangle(img, d.Box, Scalar.Red, 2);
                Cv2.PutText(img, $"{d.Label} {d.Conf:F2}", new Point(d.Box.X, d.Box.Y - 10),
                            HersheyFonts.HersheySimplex, 0.7, Scalar.Red, 2);
            }
            return img;
        }

        protected override void OnFormClosing(FormClosingEventArgs e)
        {
            timer.Stop();
            cap?.Release();
            session?.Dispose();
            base.OnFormClosing(e);
        }
    }

    public record Detection(Rect Box, float Conf, string Label);

四、运行与避坑（最简清单）

1. 模型路径：把 yolov8n.onnx 放在项目根目录或 bin/Debug/net8.0-windows
2. 摄像头索引：0 不行就改成 1、2 或 RTSP 地址
3. DLL 缺失：运行报 onnxruntime.dll not found → 项目属性 → 生成事件 → 后生成事件命令行：

   xcopy "$(NuGetPackageRoot)\microsoft.ml.onnxruntime\*\runtimes\win-x64\native\*" "$(TargetDir)" /Y /I
   

4. 内存泄漏：所有 Mat 用 using 块
5. 卡顿：调高 timer.Interval = 150（≈6–7fps）
6. 低配优化：模型换 int8 版 + IntraOpNumThreads = 1 或 2

五、快速验证步骤

1. 新建 WinForms 项目（.NET 8）
2. 安装 2 个 NuGet 包
3. 复制上面代码到 Form1.cs
4. 下载 yolov8n.onnx 放项目根目录
5. 运行 → 看到实时检测框即成功

如果您需要继续补充以下内容，请告诉我，我直接给出最简代码：

• 上升沿触发 + 防抖完整联动
• 缺陷 ROI 裁剪保存
• PLC 联动（写寄存器）
• 多相机分屏显示
• Linux 部署完整步骤

祝您快速跑通！有问题随时问我。