Ubuntu 20.04 安装 Eigen3 后编译报错“Eigen/Dense: No such file or directory”？

Question

在 Ubuntu 20.04 上通过 `apt install libeigen3-dev` 安装 Eigen3 后，C++ 项目编译时仍报错 `fatal error: Eigen/Dense: No such file or directory`，这是典型头文件路径未被正确识别的问题。根本原因在于：Eigen 是纯头文件库（header-only），其头文件实际安装在 `/usr/include/eigen3/` 下，而非 `/usr/include/Eigen/`；因此 `#include ` 要求编译器搜索路径中包含 `-I/usr/include/eigen3`，但多数 CMake 或 Makefile 默认未自动添加该路径。常见误操作包括：仅安装 `libeigen3-dev` 却未在构建系统中显式引入 `find_package(Eigen3 REQUIRED)` 并链接 `target_include_directories(... PRIVATE ${EIGEN3_INCLUDE_DIRS})`，或手动编译时遗漏 `-I/usr/include/eigen3`。此外，部分用户误删或覆盖了 `/usr/include/eigen3` 符号链接，亦会导致此错误。该问题与 Eigen 版本无关（Ubuntu 20.04 自带 Eigen 3.3.7），本质是构建配置缺失，而非安装失败。

Answer 1

```html

一、现象层：编译错误的表征与复现路径

在 Ubuntu 20.04 系统中执行 apt install libeigen3-dev 后，标准 C++ 源码中写入 #include <Eigen/Dense> 并调用 g++ main.cpp -o main 直接编译，必然触发：
fatal error: Eigen/Dense: No such file or directory。
该错误并非 Eigen 未安装，而是编译器根本未搜索 /usr/include/eigen3/ 路径——这是所有后续分析的起点。

二、结构层：Eigen 的安装布局与符号链接机制

运行以下命令可验证真实安装结构：

dpkg -L libeigen3-dev | grep -E '(/usr/include/eigen3|Eigen$)'
ls -la /usr/include/eigen3
ls -la /usr/include/Eigen

输出显示：
• 头文件全部位于 /usr/include/eigen3/Eigen/...；
• /usr/include/eigen3 是真实目录；
• /usr/include/Eigen 默认不存在（非自动创建）；
• libeigen3-dev 包 不提供 /usr/include/Eigen 符号链接——这是关键设计事实。

三、构建系统层：CMake 的典型误配与修复范式

以下是 错误 CMakeLists.txt 片段 与 正确修复方案 的对比：

问题写法	正确写法
find_package(Eigen3) target_link_libraries(myapp)	find_package(Eigen3 3.3 REQUIRED) target_include_directories(myapp PRIVATE ${EIGEN3_INCLUDE_DIRS})

注意：${EIGEN3_INCLUDE_DIRS} 在 Ubuntu 20.04 下实际值为 /usr/include/eigen3；若省略 target_include_directories，CMake 不会自动注入头文件路径——这是 90% 项目失败的根源。

四、工程实践层：Makefile 与命令行编译的显式路径注入

当脱离 CMake 使用原生 Makefile 时，必须显式声明：

CXXFLAGS += -I/usr/include/eigen3
# 或更健壮地：
EIGEN3_INC := $(shell pkg-config --cflags eigen3)
CXXFLAGS += $(EIGEN3_INC)

验证路径有效性：

pkg-config --cflags eigen3  # 输出：-I/usr/include/eigen3

此方式兼容性极强，适用于嵌入式交叉编译、CI/CD 构建脚本等受限环境。

五、运维层：符号链接异常与系统级诊断流程

若 /usr/include/eigen3 存在但失效，需按序排查：

1. 检查是否被覆盖：ls -ld /usr/include/eigen3 → 应为目录，非损坏软链
2. 验证包完整性：dpkg --verify libeigen3-dev
3. 重建符号链接（仅当确需 /usr/include/Eigen）：
   sudo ln -sf /usr/include/eigen3 /usr/include/Eigen
4. 但强烈不推荐该操作——它破坏多版本共存能力，且违反 Debian Policy。

六、原理层：为什么 Eigen 不走传统 /usr/include/Eigen？

这是 Eigen 社区与 Debian 维护者共同约定的 命名空间隔离策略：
• 支持同一系统并存 Eigen 3.x 和未来 Eigen 4.x（通过 /usr/include/eigen4）；
• 避免与用户自定义 /usr/local/include/Eigen 冲突；
• 强制构建系统显式声明依赖，提升可重现性与跨平台鲁棒性。
因此，“路径不对”不是 bug，而是 deliberate design choice。

七、高阶验证：C++20 模块化与现代构建系统的适配

在启用 C++20 Modules 的项目中，需额外处理：

#include <Eigen/Dense>  // 仍有效 —— 因为模块接口单元仍依赖传统头文件路径
// 但若使用 module interface unit (.ixx)，需在 modulemap 中显式映射：
module Eigen : Dense {
  header "Eigen/Dense"
  export *
}
// 此时仍需 -fmodule-header -I/usr/include/eigen3

这印证了：无论构建范式如何演进，-I/usr/include/eigen3 始终是底层基础设施要求。

八、横向对比：Ubuntu 20.04 vs 其他发行版的差异图谱

graph LR
  A[Ubuntu 20.04] -->|libeigen3-dev| B[/usr/include/eigen3/]
  C[Debian 11] -->|libeigen3-dev| B
  D[CentOS 8] -->|eigen3-devel| E[/usr/include/eigen3/]
  F[Arch Linux] -->|eigen| G[/usr/include/eigen3/]
  B --> H[统一路径契约]
  H --> I[所有主流发行版均遵循 /usr/include/eigen3]

结论：该路径是跨发行版事实标准，而非 Ubuntu 特例。任何假设 /usr/include/Eigen 存在的代码，本质不具备可移植性。

```