【地狱级难度】ubuntu系统GOCV编译安装

引言

在 Go 语言生态中，图像处理与计算机视觉一直是一个相对薄弱的领域，而 GoCV 作为 OpenCV 的官方 Go 绑定，为开发者提供了一条高效、可靠的落地路径。本文将围绕 GoCV 在 Linux 环境下的完整编译安装过程展开，从版本对应关系、依赖安装、源码下载，到 Makefile 修改与最终编译，逐步拆解每一个关键环节。读者将学会如何正确匹配 GoCV 与 OpenCV 的版本，规避编译过程中常见的网络下载超时问题，并掌握针对 IPP、wechat_qrcode、xfeatures2d 等慢速节点的优化配置。阅读本文前，建议读者具备基本的 Go 语言语法知识、Linux 命令行操作经验，并了解 OpenCV 的基本概念，以便更顺畅地跟随实操步骤。

版本对应关系

GoCV（gocv.io/x/gocv）不是独立视觉库，是 OpenCV 的 Go 语言 C 风格绑定包装器 ，底层直接调用原生 OpenCV 4.x C++ 库，需要系统预先编译安装 OpenCV 库文件。

项目地址：https://github.com/hybridgroup/gocv

GoCV 的 minor 版本号升级，就是为了锁定对应的 OpenCV 版本，必须严格匹配，否则编译 / 运行报错：

GoCV 版本	绑定 OpenCV 版本
v0.43.0	4.13.0
v0.42.0	4.12.0
v0.40.0	4.11.0
v0.39.0	4.10.0
v0.37.0	4.9.0
v0.33.0	4.7.0
v0.27.0	4.5.2

gocv最新只支持opencv4.13，就选择这个版本

安装依赖

bash 复制代码

sudo apt update
sudo apt install -y cmake gcc g++ git pkg-config libgtk-3-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libjpeg-dev libpng-dev libtiff-dev gfortran openexr libatlas-base-dev libopenexr-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev

手工下载opencv

方法一 github翻墙下载

手动下载 opencv + opencv_contrib，放到 /tmp/opencv（推荐，绕过 curl）

bash 复制代码

https://github.com/opencv/opencv/tree/4.13.0

bash 复制代码

https://github.com/opencv/opencv_contrib/tree/4.13.0

方法二 gitcode国内下载

下载zip源码

bash 复制代码

https://gitcode.com/GitHub_Trending/opencv31/opencv/tags/4.13.0

bash 复制代码

https://gitcode.com/gh_mirrors/op/opencv_contrib/tags/4.13.0

将源码解压，copy到tmp目录

解压

bash 复制代码

unzip opencv-4.13.0.zip 
unzip opencv_contrib-4.13.0.zip

创建临时目录

bash 复制代码

cd /tmp
mkdir opencv

复制到临时目录

bash 复制代码

cp -rf opencv-4.13.0 /tmp/opencv
cp -rf opencv_contrib-4.13.0 /tmp/opencv

保证目录结构是

bash 复制代码

/tmp/opencv/
├── opencv-4.13.0
└── opencv_contrib-4.13.0

修改Makefile

将opencv的下载注释掉，再额外加一行，不然会报错，如下

bash 复制代码

# Download OpenCV source tarballs.
download:
        #rm -rf $(TMP_DIR)opencv
        #mkdir $(TMP_DIR)opencv
        #cd $(TMP_DIR)opencv
        #curl -Lo opencv.zip https://github.com/opencv/opencv/archive/refs/tags/$(OPENCV_VERSION).zip
        #unzip -q opencv.zip
        #curl -Lo opencv_contrib.zip https://github.com/opencv/opencv_contrib/archive/refs/tags/$(OPENCV_VERSION).zip
        #unzip -q opencv_contrib.zip
        #rm opencv.zip opencv_contrib.zip
        @echo "===== Skip auto download, use manually placed OpenCV source ====="

执行编译

找个地方clone，比如 ~/work

bash 复制代码

mkdir -p ~/work
cd ~/work
git clone https://github.com/hybridgroup/gocv.git
cd gocv

切换到 v0.43.0，或者直接手工下载这个分支

bash 复制代码

git checkout v0.43.0

最后执行编译，这个地方自己会加sudo权限，注意之前都不要加sudo

bash 复制代码

make install

如果编译失败，需要sudo清空tmp

bash 复制代码

sudo rm -rf /tmp/opencv

会有几个下载慢的节点

节点1（IPP）

bash 复制代码

-- IPPICV: Downloading ippicv_2022.2.0_lnx_intel64_20250730_general.tgz from https://raw.githubusercontent.com/opencv/opencv_3rdparty/c934a2a15a6df020446ac3dfa07e3acf72b63a8f/ippicv/ippicv_2022.2.0_lnx_intel64_20250730_general.tgz
-- found Intel IPP (ICV version): 2022.2.0 [2022.2.0]
-- at: /tmp/opencv/opencv-4.13.0/build/3rdparty/ippicv/ippicv_lnx/icv
-- found Intel IPP Integration Wrappers sources: 2022.2.0

IPP = Intel Integrated Performance Primitives ，英特尔多媒体 / 图像信号高性能原语库；OpenCV 内置裁剪后的子集叫 IPP-ICV，免费，只给 OpenCV 使用

这个30M，有概率下载成功，建议直接关掉

bash 复制代码

-D WITH_IPP=OFF \

注意：

即使禁用了，可能也会下载，只不过不会编译了，放心等待继续即可

节点2（wechat_qrcode）

bash 复制代码

-- wechat_qrcode: Downloading detect.caffemodel from https://raw.githubusercontent.com/WeChatCV/opencv_3rdparty/a8b69ccc738421293254aec5ddb38bd523503252/detect.caffemodel
-- wechat_qrcode: Downloading detect.prototxt from https://raw.githubusercontent.com/WeChatCV/opencv_3rdparty/a8b69ccc738421293254aec5ddb38bd523503252/detect.prototxt

wechat_qrcode：微信开源 CNN 二维码识别模块

即使关掉，OpenCV 原生基础二维码 cv::QRCodeDetector 还能用，只是识别弱一点。

解决方案：
增加配置，不下载它

bash 复制代码

-D BUILD_opencv_wechat_qrcode=OFF \

节点3（xfeatures2d）

bash 复制代码

-- xfeatures2d/boostdesc: Downloading boostdesc_binboost_256.i from https://raw.githubusercontent.com/opencv/opencv_3rdparty/34e4206aef44d50e6bbcd0ab06354b52e7466d26/boostdesc_binboost_256.i
-- Try 1 failed
CMake Warning at cmake/OpenCVDownload.cmake:251 (message):
  xfeatures2d/boostdesc: Download failed: 28;"Timeout was reached"

  For details please refer to the download log file:

  /tmp/opencv/opencv-4.13.0/build/CMakeDownloadLog.txt

Call Stack (most recent call first):
  /tmp/opencv/opencv_contrib-4.13.0/modules/xfeatures2d/cmake/download_boostdesc.cmake:22 (ocv_download)
  /tmp/opencv/opencv_contrib-4.13.0/modules/xfeatures2d/CMakeLists.txt:16 (download_boost_descriptors)

xfeatures2d：2D 特征点实验 / 专利算法模块OpenCV

包含经典算法：SIFT、SURF、BRISK、FREAK、DAISY、BoostDesc 等关键点检测 + 描述子。
典型场景：图像拼接、物体模板匹配、全景图、SLAM、三维重建、图像检索。
你设置 OFF：不编译这一整套特征点算法。
✅ 如果你只做：RTSP 拉流、YOLO 目标检测、图像裁剪缩放、DNN CUDA 推理，完全用不到 SIFT/SURF，放心 OFF。

注意：OpenCV 主库自带普通 ORB 还能继续使用，ORB 不在 xfeatures2d 里面

这个有好多，是下载好慢的，增加参数，不下载它

bash 复制代码

-D BUILD_opencv_xfeatures2d=OFF \

带尝试操作

我是直接转成功了，如果不成功尝试下面操作

opencv4.5以上版本可以指向gitcode下载第三方源

bash 复制代码

-D OPENCV_DOWNLOAD_MIRROR_ID=gitcode \

也可以尝试禁用第三方下载

bash 复制代码

-D OPENCV_DOWNLOAD_3RDPARTY=OFF \

CUDA_ARCH_BIN=5.3 这点很关键

5.3：Maxwell 架构，比如 Jetson TX2；
如果你是桌面 RTX 卡（20 系 / 30 系 / 40 系），5.3 完全不对，编译出来无法调用 GPU
- RTX20xx：7.5
- RTX30xx：8.6
- RTX40xx：8.9

推荐配置，直接复制进Makefile

bash 复制代码

cmake -D CMAKE_BUILD_TYPE=RELEASE \
                -D CMAKE_INSTALL_PREFIX=/usr/local \
                -D EIGEN_INCLUDE_PATH=/usr/include/eigen3 \
                -D BUILD_SHARED_LIBS=${BUILD_SHARED_LIBS} \
                -D OPENCV_EXTRA_MODULES_PATH=$(TMP_DIR)opencv/opencv_contrib-$(OPENCV_VERSION)/modules \
                -D BUILD_DOCS=OFF -D BUILD_EXAMPLES=OFF -D BUILD_TESTS=OFF -D BUILD_PERF_TESTS=OFF -D BUILD_opencv_java=OFF -D BUILD_opencv_python=OFF -D BUILD_opencv_python2=OFF -D BUILD_opencv_python3=OFF \
                -D WITH_OPENCL=OFF \
                -D WITH_CUDA=ON \
                -D CUDA_ARCH_BIN=8.9 \
                -D CUDA_ARCH_PTX="" \
                -D WITH_CUDNN=ON \
                -D WITH_CUBLAS=ON \
                -D ENABLE_FAST_MATH=ON \
                -D CUDA_FAST_MATH=ON \
                -D OPENCV_DNN_CUDA=ON \
                -D ENABLE_NEON=ON \
                -D WITH_QT=OFF \
                -D WITH_OPENMP=ON \
                -D WITH_OPENGL=ON \
                -D BUILD_TIFF=ON \
                -D WITH_FFMPEG=ON \
                -D WITH_GSTREAMER=ON \
                -D WITH_TBB=OFF \
                -D BUILD_TBB=OFF \
                -D BUILD_TESTS=OFF \
                -D WITH_EIGEN=ON \
                -D WITH_V4L=ON \
                -D WITH_LIBV4L=ON \
                -D WITH_IPP=OFF \
                -D BUILD_opencv_wechat_qrcode=OFF \
                -D BUILD_opencv_xfeatures2d=OFF \
                -D WITH_LIBV4L=ON \
                -D WITH_JPEG2K=OFF \
                -D OPENCV_DOWNLOAD_3RDPARTY=OFF \
                -D OPENCV_GENERATE_PKGCONFIG=ON ..