Linux 下使用 Eclipse CDT 开发 OpenCV 应用：从新建项目、链接配置到运行的完整指南

本文是面向 Linux 桌面开发者的 OpenCV 集成实战指南，讲解如何在安装了 Eclipse（CDT 插件，即 C/C++ 开发工具集）的 IDE 中创建、配置、编译并运行基于 OpenCV 的图像显示程序。教程覆盖两条典型开发路线：一是通过 Eclipse 原生 C/C++ 项目手动填写头文件与库路径（适合不引入构建系统的最小项目），二是借助 CMake 生成 Makefile 后再导入 Eclipse（适合已有 CMake 工程、需要 IDE 辅助编码与调试的场景）。读完本文，你将掌握 Eclipse 环境下 OpenCV include 路径、链接库、运行参数的完整配置方法，并能自行复现出可弹窗显示图片的可执行程序。

适用说明：本文依据 OpenCV 官方入门文档 Using OpenCV with Eclipse (plugin CDT) 编写，源码细节以本仓库为准。原教程成文较早，Eclipse/CDT 界面在不同版本间有差异，原文档也标注了 “This tutorial can contain obsolete information.”，因此下文涉及的菜单名称与库模块列表可能随你的 Eclipse、OpenCV 版本而变化，实际操作时请以本机界面和 pkg-config/CMake 输出为准。

前置条件

开始之前，需要准备两样东西：

1. 已安装 Eclipse（仅需 CDT 的 C/C++ 支持）。到 Eclipse 官网下载 Eclipse IDE for C/C++ Developers 对应你工作站的版本（或从 Marketplace 给标准 Eclipse 安装 CDT 插件）。解压后直接运行目录中的可执行文件即可启动。
2. 已安装 OpenCV。若尚未安装，请先参考 Linux 下的源码安装教程 完成构建与 make install。通常安装前缀为 /usr/local，头文件位于 /usr/local/include/opencv2，库文件位于 /usr/local/lib。

需要说明的是，本仓库当前为 OpenCV 5 系列源码（参见 OpenCVGenPkgconfig.cmake 中默认生成的 pkg-config 文件名为 opencv5.pc，仅在启用 mangled 安装路径时才命名为 opencv-<版本号>.pc）。因此老文档中 pkg-config opencv 这样的写法，在较新发行版/新版本 OpenCV 下包名可能变为 opencv5 或带版本号，请以下面章节的说明为准。

路线一：直接创建 C/C++ 项目并手动链接 OpenCV

这条路线完全不引入构建脚本，适合快速验证、教学和小型工具，Eclipse 直接调用 make 完成编译。

第 1 步：创建项目

1. 启动 Eclipse，在菜单栏执行 File -> New -> C/C++ Project。

   

2. 为项目命名（示例为 DisplayImage），模板选择 Empty Project（空项目）。

3. 其余选项保持默认，点击 Finish。项目会出现在左侧 Project Navigator（Project Explorer）中。

第 2 步：添加源文件

1. 在导航器中右键点击 DisplayImage，选择 New -> Folder，新建名为 src 的文件夹，点击 Finish。
2. 右键点击 src 文件夹，选择 New -> Source File，命名为 DisplayImage.cpp 并完成创建。

第 3 步：编写示例代码

将下列代码完整复制进 DisplayImage.cpp。它的作用是用命令行参数指定一张图片路径，读取后弹出一个自适配大小的窗口显示图像，按任意键关闭窗口：

#include <opencv2/opencv.hpp>
#include <cstdio>   // printf

using namespace cv;

int main( int argc, char** argv )
{
  // 尚未传入图片参数时，argv[1] 非法，先判断再使用
  if( argc != 2 )
  {
    printf( "Usage: DisplayImage <image_path>\n" );
    return -1;
  }

  Mat image;
  image = imread( argv[1], IMREAD_COLOR );   // 以 3 通道 BGR 彩色读入

  if( !image.data )
  {
    printf( "No image data \n" );
    return -1;
  }

  namedWindow( "Display Image", WINDOW_AUTOSIZE );  // 窗口尺寸随图像自动调整
  imshow( "Display Image", image );                 // 在窗口中渲染图像

  waitKey(0);     // 无限等待键盘输入，返回后程序结束

  return 0;
}

上述四个核心 API 都在本仓库源码中可查证，值得理解其默认行为：

• cv::imread：声明于 modules/imgcodecs/include/opencv2/imgcodecs.hpp，负责解码图像文件。其 flags 参数默认值为 IMREAD_COLOR_BGR（同 IMREAD_COLOR，值为 1），即始终把图片转为 3 通道 BGR 彩色图像；取 IMREAD_GRAYSCALE（0）会转成单通道灰度图，取 IMREAD_UNCHANGED（-1）则按文件原始格式（含 alpha 通道）返回，具体取值可查 imgcodecs.hpp。读取失败时返回的 Mat 的 data 为空，因此示例用 !image.data 做健壮性判断。
• cv::namedWindow：声明于 modules/highgui/include/opencv2/highgui.hpp。第二个参数为窗口标志，默认即 WINDOW_AUTOSIZE（值为 1），表示用户不能缩放窗口，窗口尺寸由所显示图像决定；若想允许缩放，可改用 WINDOW_NORMAL（0），完整标志表见 highgui.hpp。
• cv::imshow：声明于 highgui.hpp，把 Mat 绘制到指定名称的窗口。图像显示与消息循环由 highgui（Linux 下常由 GTK/Qt 后端实现）驱动。
• cv::waitKey：声明于 highgui.hpp，参数 delay 为等待毫秒数，默认 0 表示无限等待直至有按键输入。只有调用了 waitKey，窗口事件循环才会真正刷新画面，因此 imshow 之后必须搭配它。

（原教程的这段示例是在读图之后才判断 argc != 2，属于历史遗留瑕疵——若不带参数运行会先越界访问 argv[1]。上面给出的版本已把参数个数判断提前，逻辑更严谨，可直接复制使用。）

第 4 步：配置头文件路径

程序引用了 <opencv2/opencv.hpp>，编译器必须能找到 OpenCV 头文件目录。配置路径如下：

1. 右键项目选择 Properties（属性）。
2. 进入 C/C++ Build -> Settings，右侧选择 Tool Settings 标签页。
3. 展开 GCC C++ Compiler，选择 Includes，在 Include paths (-l)（实际对应 -I 编译选项）中添加 OpenCV 安装位置的头文件目录。示例安装前缀下为 /usr/local/include/opencv2（更稳妥的是把 /usr/local/include 也一并加上）。

如果你不确定 OpenCV 装到了哪里，可以在 Terminal 里用 pkg-config 查询：

pkg-config --cflags opencv

在我的机器上输出为（示例路径，随安装而异）：

-I/usr/local/include/opencv -I/usr/local/include

底层原理：这条命令读取的是 OpenCV 安装时生成的 .pc 元数据文件。仓库的 opencv-XXX.pc.in 模板 记录了 includedir、libdir 与 Libs（-l 库列表），安装后会被放到 ${libdir}/pkgconfig 目录，相关生成与安装逻辑见 cmake/OpenCVGenPkgconfig.cmake。由于本仓库默认生成的包名为 opencv5.pc，新版 OpenCV 下更常见的查询命令是：

pkg-config --cflags opencv5

务必以你机器上实际生成的 .pc 文件名（ls /usr/local/lib/pkgconfig 查看）为准，老教程里的 opencv 包名在新版本中可能已不再适用。

第 5 步：配置链接库

1. 仍在 Tool Settings 标签页，展开 GCC C++ Linker：

   • Library search path (-L)：填入 OpenCV 库文件所在目录，示例为 /usr/local/lib。
   • Libraries (-l)：逐个添加需要链接的 OpenCV 模块库名（不带 lib 前缀与 .so 后缀）。

2. 原教程把下面这一整串都加了进去（对应其安装版本的全部模块）：

opencv_core opencv_imgproc opencv_imgcodecs opencv_highgui opencv_videoio
opencv_video opencv_features opencv_geometry opencv_objdetect opencv_flann

说明两点：

• 其实可以更精简。DisplayImage 实际用到的 API 只涉及三个模块：图像内存与基础数据结构 opencv_core、图像编解码 opencv_imgcodecs、窗口 GUI opencv_highgui。由于后两者存在对 opencv_imgproc、opencv_core 的依赖，简单程序链入 opencv_core opencv_imgproc opencv_imgcodecs opencv_highgui 通常就足够了（原文档也提示“一般只需前四个”）。
• 模块名随版本演变。教程撰写年代的模块（如 opencv_features、opencv_geometry、opencv_calib）与当前仓库的模块划分已有差异——本仓库的模块清单在 modules 下可见（如 core、imgproc、imgcodecs、highgui、videoio、video、features、geometry、calib、objdetect、flann、photo、dnn 等），每个模块编译出的库名为 libopencv_<模块名>.so。因此最可靠的做法是依赖 pkg-config 自动给出完整列表：

pkg-config --libs opencv5

示例输出（与老版本输出结构一致，内容取决于实际构建出的模块集）：

-L/usr/local/lib -lopencv_core -lopencv_imgproc -lopencv_imgcodecs
-lopencv_highgui -lopencv_videoio -lopencv_video -lopencv_flann ...

配置完成后点击 OK 保存。

第 6 步：编译整个项目

菜单栏执行 Project -> Build all。Eclipse 会在 Console 视图中调用 make 输出编译过程，成功时会看到 Finished building target: DisplayImage 之类的提示；项目目录下也会生成可执行文件（Debug 配置下通常位于 Debug/DisplayImage）。

第 7 步：在 Eclipse 中运行并传入图片参数

命令行方式下，运行命令类似：

cd <DisplayImage_directory>
cd src
./DisplayImage ../images/HappyLittleFish.png

（假设图片位于 <DisplayImage_directory>/images/HappyLittleFish.png。仓库的 samples/data 目录下有大量可用测试图片，例如 lena.jpg、messi5.jpg 等，可拷贝一份到项目下使用。）也可以直接在 Eclipse 里完成这一切：

1. 菜单栏执行 Run -> Run Configurations。
2. 左侧 C/C++ Application 下会列出 DisplayImage Debug（若没有，多点击几次该节点刷新），选中它。
3. 右侧切换到 Arguments 标签页，填写要打开的图片路径。注意路径是相对于 workspace/DisplayImage（项目根目录）而言的，例如把图片放进项目根目录后直接填写文件名。
4. 点击 Apply，再点击 Run。屏幕会弹出 OpenCV 窗口并显示该图片。

常见坑：若运行时提示找不到 libopencv_*.so，是因为 /usr/local/lib 不在动态链接器的默认搜索路径中。请在运行前导出：

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

更持久的方式是把 /usr/local/lib 写入 /etc/ld.so.conf.d/ 下的配置并执行 sudo ldconfig。

至此你就完成了 路线一——在 Eclipse 中直接构建并运行 OpenCV 程序，可以在 IDE 里愉快地进行后续开发了。

路线二：CMake + OpenCV + Eclipse CDT（导入已有 Makefile 项目）

当项目规模变大、依赖变多时，手填库路径既繁琐又易错。更工程化的做法是：用 CMake 描述依赖关系并生成 Makefile，再把项目作为 “Makefile Project” 导入 Eclipse，让 Eclipse 负责索引代码、触发构建与调试，而链接规则完全交给 CMake 管理。

第 1 步：编写示例源文件与 CMakeLists.txt

新建目录 foo，在其中创建 helloworld.cpp，内容为创建一个 640×480 的单通道灰度图并叠加 “Hello World!” 文字后显示：

#include <opencv2/opencv.hpp>
using namespace cv;

int main ( int argc, char **argv )
{
  Mat img(480, 640, CV_8U);                          // 640x480 单通道灰度图
  putText(img, "Hello World!", Point( 200, 400 ),
          FONT_HERSHEY_SIMPLEX | FONT_ITALIC, 1.0,
          Scalar( 255, 255, 0 ));                    // 文字颜色（此处按 BGR 视作纯亮）
  imshow("My Window", img);
  waitKey();
  return 0;
}

cv::putText 的完整签名声明于 modules/imgproc/include/opencv2/imgproc.hpp，参数依次为：图像、文字内容、文本左下角坐标 org、字体（HersheyFonts 系列，如 FONT_HERSHEY_SIMPLEX，可与 FONT_ITALIC 组合）、字号缩放 fontScale、颜色 color，以及可选的线宽 thickness（默认 1）与线型 lineType（默认 LINE_8）。fontScale 大于 1 放大文字、介于 0~1 缩小文字（参数语义说明见 imgproc.hpp）。

说明：单通道 CV_8U 图像上的彩色文字最终会显示为灰阶效果，若要看到彩色文字可改用 CV_8UC3 三通道图。这是原教程示例代码本身的特性，不影响对 CMake+Eclipse 流程的演示。

然后在 build 目录下创建 CMakeLists.txt（注意路径：原文档这里存在笔误，实际应把 CMakeLists.txt 与源码放同一工程目录，或按下文统一放到源目录 foo 下，cmake 的源码目录与构建目录分离）：

cmake_minimum_required(VERSION 3.13)
PROJECT( helloworld_proj )

# 查找 OpenCV 安装，REQUIRED 表示找不到即报错
FIND_PACKAGE( OpenCV REQUIRED )

# 由 helloworld.cpp 生成可执行目标
ADD_EXECUTABLE( helloworld helloworld.cpp )

# 链接 OpenCV 的全部库（变量内容由 find_package 填充）
TARGET_LINK_LIBRARIES( helloworld ${OpenCV_LIBS} )

find_package(OpenCV) 做了什么？ 它在 CMAKE_PREFIX_PATH（或 OpenCV_DIR）指向的安装前缀下查找 OpenCV 官方提供的 OpenCVConfig.cmake（该配置文件由 cmake/templates/OpenCVConfig.cmake.in 生成）。找到后会自动导出若干变量：OpenCV_LIBS（需链接的库完整列表）、OpenCV_INCLUDE_DIRS、OpenCV_VERSION、OpenCV_DIR 等。仓库自带的最小示例 samples/CMakeLists.example.in 展示了与此一致的标准写法：先用 find_package(OpenCV REQUIRED)，再用 add_executable 声明目标，最后 target_link_libraries(... ${OpenCV_LIBS})。如果你的 OpenCV 不在默认搜索路径，需在执行 cmake 时显式指定：

cmake -D OpenCV_DIR=/usr/local/lib/cmake/opencv5 ..

（OpenCV_DIR 指向包含 OpenCVConfig.cmake 的目录，具体路径请用 find /usr/local -name OpenCVConfig.cmake 确认，通常安装于 lib/cmake/opencv5/。）

第 2 步：用 cmake-gui 生成 Makefile

1. 打开终端，在 foo 下创建独立构建目录并进入：

cd foo
mkdir build && cd build
cmake-gui ..

2. 在 cmake-gui 中确认源码目录与构建目录无误，若自动探测不到 OpenCV，则手动填入 OpenCV_DIR 指向 OpenCV 的 cmake 配置目录。
3. 点击 Configure 再点击 Generate，成功后退出 cmake-gui。
4. 在 build 目录执行 make -j4（-j4 表示用 4 个并行任务编译，可省略）验证能成功构建出 helloworld 可执行文件。

第 3 步：以 Makefile 项目方式导入 Eclipse

1. 启动 Eclipse，把 workspace 指向任意目录（不要放在 foo 或 foo/build 内）。
2. 在 Project Explorer 中右键，选择 Import，在 C/C++ 分类下选择 Existing Code as a Makefile Project。
3. 项目名命名为 helloworld，Existing Code Location 浏览选择 foo/build（即刚才运行 cmake-gui 并生成 Makefile 的目录）。
4. Toolchain for Indexer Settings 选择 Linux GCC，点击 Finish。

第 4 步：调整构建目录与构建命令

1. 右键项目选择 Properties，进入 C/C++ Build，把 Build directory 从默认的 ${workspace_loc:/helloworld} 改为 ${workspace_loc:/helloworld}/build——因为 Makefile 与中间产物都在 build 子目录中。
2. （可选）把 Build command 从 make 改为 make VERBOSE=1 -j4：VERBOSE=1 会让 make 打印每条完整的编译/链接命令，便于排查头文件与库路径问题，同时用 4 个线程并行加速构建。

保存后 Eclipse 的构建按钮就会在 build 目录里驱动 make，索引器（Indexer）会解析工程内全部源码并提供跳转、补全与实时报错。至此 路线二 配置完成。

总结与故障排查

两种集成方式的适用场景不同：手动配置 CDT 工程适合不引入额外构建工具的轻量程序，可视化地看到 -I 与 -l 的具体含义；CMake + 导入 Makefile 工程适合严肃项目，依赖描述单一可信源、跨 IDE/跨平台可移植。无论哪条路线，都建议在终端用 pkg-config --cflags opencv5 / pkg-config --libs opencv5 交叉核对路径是否正确。

高频问题速查：

现象	原因	处理
编译报错 opencv2/opencv.hpp: No such file or directory	Include path 未配置	在 Tool Settings 的 GCC C++ Compiler -> Includes 中补充 /usr/local/include（或按 pkg-config 输出）
链接报错 undefined reference to cv::imread 等	缺少对应 -l 库	加入 -lopencv_imgcodecs -lopencv_core -lopencv_highgui，或用 pkg-config --libs opencv5 一键获取
链接报错 cannot find -lopencv_xxx	库搜索路径不对	检查 Library search path 是否为 /usr/local/lib，并确认该库确实被构建
运行报错 error while loading shared libraries	运行时找不到 .so	设置 LD_LIBRARY_PATH=/usr/local/lib 或执行 ldconfig
pkg-config 找不到包	包名与安装版本不匹配	执行 ls /usr/local/lib/pkgconfig/ 确认真实文件名（本仓库为 opencv5.pc）后重试

配置完成后，你就拥有了一个“Eclipse 编辑 + OpenCV 运行”的桌面视觉开发环境。更进一步，可以继续阅读 在 Linux 下用 GCC/CMake 命令行构建 OpenCV 的教程 对比两种工作流的差异，或在 Windows 上参考 Windows 平台安装 OpenCV 完成类似配置。