CMake 安装到自定义目录为什么路径不对

CMake 安装到自定义目录后发现文件“跑错地方”，最常见的原因不是安装命令失效，而是把三个层次混在了一起：配置时的 CMAKE_INSTALL_PREFIX、执行安装时的 --prefix，以及 install() 里的 DESTINATION。先把这三者拆开，再看最终文件树，路径问题通常很快就能定位。

官方地址：https://cmake.org/cmake/help/latest/command/install.html

相对的 DESTINATION 会落在安装前缀下面；cmake --install --prefix 可以覆盖本次安装使用的前缀，但绝对的 DESTINATION 是固定路径，不会跟着这个覆盖值移动。

先看清“安装入口”在哪里

我通常先从构建目录开始排查，而不是直接翻项目源代码。CMake 的安装规则已经写入生成后的构建树，真正执行安装时应该把 cmake --install 指向这个构建目录。

# 进入已经完成 configure 和 build 的构建目录
cd build

# 先确认有哪些安装规则，再把本次安装放到可观察的自定义目录
cmake --install . --prefix "$PWD/stage"

# 从安装前缀开始查看文件，避免把 build 目录误当成安装结果
find "$PWD/stage" -maxdepth 4 -type f -print

这组命令里的 build 是构建树，stage 才是本次安装的目标前缀。若命令成功但文件树仍然不符合预期，下一步就要回到 install() 的目的地设置，而不是反复修改构建命令。

配置前缀和本次安装前缀不是同一个开关

CMAKE_INSTALL_PREFIX 是配置阶段的变量，通常在第一次生成构建树时写入缓存。--prefix 是 cmake --install 的命令行选项，作用范围只覆盖当前这次安装调用。

# 配置阶段：把默认安装前缀写入构建缓存
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/sample-app

# 构建阶段：只生成目标，不改变安装前缀
cmake --build build

# 安装阶段：临时把这一次安装改到 workspace/stage
cmake --install build --prefix "$PWD/workspace/stage"

如果项目没有在配置阶段固定奇怪的路径，最后一条命令会让相对目的地落在 workspace/stage 下。反过来，如果你只修改了 CMAKE_INSTALL_PREFIX 但没有重新配置，旧构建树仍可能保留旧值；这时先看缓存，再决定是否重新执行 configure。

入口位置：在项目面板里先定位构建树

使用带有 CMake 工作区面板的编辑器或构建工具时，先打开项目的 CMake 配置页，在“构建目录 / Build directory”字段确认当前构建树，再进入“安装 / Install”动作。界面说明图中的路径和按钮是原创示意，用来帮助定位操作区域，不代表某个软件的真实截图。

1. 在项目侧栏打开 CMake 配置或构建设置。
2. 确认“构建目录”指向已经生成构建文件的目录，而不是源码目录。
3. 展开安装命令区域，把 --prefix 指向一个空的 staging 目录。
4. 执行安装后，先看状态栏显示的目标前缀，再检查文件树。

如果面板里显示的是源码目录，或者安装按钮实际复用了另一个构建配置，路径偏差会被误认为是 DESTINATION 的问题。先校准入口，后面得到的文件树才有意义。

相对 DESTINATION 会怎样拼到前缀下面

项目的安装规则决定“前缀下面的哪一级目录”。推荐把 DESTINATION 写成相对路径，例如 bin、lib 或 share/sample-app，不要在项目里手工拼接 CMAKE_INSTALL_PREFIX。

# 把可执行文件安装到前缀下的 bin 目录
install(TARGETS sample_app
  RUNTIME DESTINATION bin
)

# 把只读资源安装到前缀下的 share/sample-app 目录
install(DIRECTORY assets/
  DESTINATION share/sample_app
)

如果本次命令是 cmake --install build --prefix /tmp/sample，相对目的地会形成类似 /tmp/sample/bin 和 /tmp/sample/share/sample_app。这里的拼接关系是排查路径的核心：前缀是根，DESTINATION 是根下面的相对位置。

绝对 DESTINATION 为什么不跟着 --prefix 走

下面这类写法会把文件直接放到绝对路径。它看起来像是“写得更明确”，但也切断了安装前缀的可重定位能力：

# 绝对路径会固定到该位置，不会被 cmake --install --prefix 替换
install(FILES config/sample.conf
  DESTINATION /etc/sample_app
)

因此，命令行即使指定了 --prefix /tmp/sample，这个配置文件仍然不会出现在 /tmp/sample/etc/sample_app。如果目标是让开发者、打包脚本或测试环境自由选择前缀，应该把目的地改成相对路径，并让前缀负责整体搬移。

文件树核对：三处信息要能对上

路径排查不要只看命令行最后一行。把下面三处信息并排放在一起，基本就能知道偏差发生在哪一层：

# 读取构建缓存中的默认前缀；没有该键时说明构建树可能未按预期配置
grep '^CMAKE_INSTALL_PREFIX:' build/CMakeCache.txt

# 用一个全新的 staging 目录观察本次安装的相对路径
rm -rf ./stage-cmake-path
cmake --install build --prefix "$PWD/stage-cmake-path"

# 只列出 staging 下的结果，便于和 DESTINATION 逐项对照
find ./stage-cmake-path -maxdepth 5 -print

如果相对目录正确而绝对目录仍出现在系统路径，说明不是 --prefix 失效，而是项目规则明确要求了绝对目的地。此时要修复的是 install() 写法，或接受该系统级目录是项目设计的一部分。

什么时候重新配置，什么时候只覆盖本次安装

只想把同一份构建产物复制到另一个 staging 目录时，使用 --prefix 就够了；想改变项目默认安装位置、影响生成阶段的路径判断或让后续安装都采用新默认值时，再重新配置 CMAKE_INSTALL_PREFIX。

• 临时测试、打包前 staging：使用 cmake --install build --prefix ...。
• 项目默认目录或新构建树：重新执行 cmake -S . -B build -D CMAKE_INSTALL_PREFIX=...。
• 无论哪种方式，都优先保持 DESTINATION 为相对路径。

这样处理还能避免把配置阶段的默认值和一次性的发布目录混成一个不可解释的路径。每次安装都先指定一个空 staging 目录，结果更容易观察，也不容易误覆盖机器上已有文件。

常见问题

为什么我改了 CMAKE_INSTALL_PREFIX，安装目录还是旧的？

它可能只是改了命令行文本，没有重新配置构建树。先检查 CMakeCache.txt，必要时重新执行 configure，再构建和安装。

--prefix 能不能覆盖绝对 DESTINATION？

不能。绝对目的地按规则直接使用，不会被本次安装的 --prefix 拼接或替换。

build 目录里有文件，为什么自定义目录里没有？

构建产物和安装产物不是同一棵目录树。只有写入 install() 规则并执行 cmake --install 的文件，才会出现在安装前缀下面。

验收时只看这四件事

1. 执行安装的构建目录确认无误。
2. 本次命令中的 --prefix 与预期 staging 路径一致。
3. 相对 DESTINATION 位于前缀下面，绝对 DESTINATION 按固定路径解释。
4. 最终文件树与安装规则逐项对应，没有把 build 目录误当成安装结果。