1. 一次跨平台编译翻车现场，以及它暴露的真问题

先说句实话：C++跨平台开发，十个人里有九个不是在写业务逻辑，而是在跟"平台差异"搏斗。我自己第一次正经做跨平台项目（一个某跨平台图像处理Demo，要在Windows、Linux、macOS三端跑起来），就狠狠栽过一次。

当时的场景特别典型：在Windows上用Visual Studio编译得好好的，代码逻辑自测也没问题，一放到Linux上，直接编译失败。报错信息干干净净一行字——某个头文件找不到。我当时第一反应是"依赖没装齐"，一查，依赖一个不少，环境变量也对。折腾了半小时才发现，不是依赖的问题，是代码里混用了Windows特有的头文件和API。

这个场景相信做C++跨平台开发的朋友都不陌生。真正问题不是"跨平台太难"，而是很多开发者在立项时没有认真想过一件事：跨平台开发不是"写一套代码到处编译"，而是"设计一套能管理平台差异的架构"。

这篇文章不打算给你画一整套理论，就围绕我实际做过的跨平台项目，讲讲我怎么选型、怎么搭构建系统、怎么处理那些教科书里不会提的差异坑、怎么用一套代码在三个系统上稳定产出。适合刚想进军跨平台C++、或者已经在做但总被平台问题卡住的开发者。看完你至少能避开我踩过的坑，知道从哪下手去搭一个不折腾的跨平台工程。

2. 编译器与标准库矩阵：跨平台开发的第一道分野

很多人选编译器只看"哪个快"，实际上在跨平台场景里，编译器选择直接决定了你要面对多少平台差异。我的经验是：别选"唯一真神"，要选"三端都有覆盖"的编译策略。

2.1 三端编译器的真实差异点

我们在项目里同时使用了MSVC、GCC、Clang三套工具链，踩过的差异大致可以分成三类。

第一类是标准库实现差异。同一段std::filesystem代码，在MSVC上跑得好好的，在GCC（libstdc++）上可能因为路径编码问题返回不一样的结果；在Clang（libc++）上又有细微差别。比如Windows下路径是宽字符处理，Linux下是UTF-8字节流，std::filesystem::path::string()返回值在不同平台上的编码语义完全不同，一旦接口后面跟着字符串拼接、比较、写入配置，就会出玄学bug。

第二类是编译警告和错误处理的严格度差异。MSVC对很多未定义行为是"睁一只眼闭一只眼"，GCC和Clang则直接报错或警告。我们项目里有个经典案例：一段指针类型转换的代码，MSVC编译零警告，GCC甩出一条-Wcast-align警告，Clang在部分架构上直接产生非法指令。同一个未定义行为，三套编译器给出三种结果，这种坑排查起来极其痛苦。

第三类是预处理器宏。_WIN32、__linux__、__APPLE__这种是最基本的，真正麻烦的是编译器自定义宏的覆盖范围。比如MSVC特有的_MSC_VER，Clang在Windows下也会定义它，如果你用#ifdef _MSC_VER去判断"是不是Windows"，就会写出一堆隐晦的bug。更稳妥的做法是用平台宏判断操作系统，用编译器宏解决编译器差异问题，两者职责分离。

2.2 我推荐的三端组合拳

我的建议是：主力开发用Clang，兼容性验证用GCC和MSVC，发布时每端都用该平台的原生工具链重新编译一遍。理由很简单：Clang的诊断信息是三者里最友好的，出问题时候的报错可读性最高，适合日常开发快速定位；GCC在Linux服务器场景下是事实标准，发布前必须用GCC跑一遍确认兼容；Windows上最终打包还是得靠MSVC，因为部分系统级API和运行时行为跟MSVC绑定得最紧密。

C++标准选择上，我们的经验是C++17起步。C++17带来的std::filesystem、std::optional、结构化绑定、内联变量，每一个都是跨平台开发能实打实省事的特性。C++20的std::span、概念、协程确实好用，但三端编译器的C++20支持度在真实项目里仍有零星落后，尤其是modules，到现在三端行为都没完全对齐。如果你的项目不是非要不可，C++17是当前跨平台开发里性价比最高的基准线。

实操提示：项目里最好在CMakeLists.txt里显式指定CXX_STANDARD 17并设置CXX_STANDARD_REQUIRED ON，否则部分编译器会用默认标准编译，行为差异会被掩盖一大截。

3. CMake：跨平台构建的骨架，但骨架也会散架

构建系统这块，业界其实争论过很久，结论基本收敛到CMake。不否认它有语法丑、调试难、文档差的毛病，但三端原生支持、生态最全、IDE适配最好这三个优点，就足够让它成为跨平台C++的事实标准。

3.1 为什么CMake是"不得不选"的那个

在Windows上有Visual Studio的工程文件（.sln/.vcxproj），Linux上有Makefile，macOS上有Xcode工程。这三种格式互不兼容，如果用它们直接管理项目，维护成本会指数级上升——每改一次文件列表，三个工程都要动一遍。CMake的价值在于：你把构建逻辑用CMake语言写一份，它能生成世界上所有主流构建系统的工程文件。

具体操作上，还有个关键点：CMake本身就自带跨平台抽象能力。比如target_link_libraries里传的库名，CMake会在Windows上自动处理成.lib导入库，在Linux/macOS上处理成.so/.a/.dylib，不需要你手动判断后缀。再比如install()命令安装的目标，在Windows上装到指定目录，在Linux上装到标准系统路径，行为都能通过一条命令统一控制。

3.2 最容易翻车的CMake配置细节

第一个坑是构建类型。单配置生成器（Unix Makefiles、Ninja）需要你在命令行用-DCMAKE_BUILD_TYPE=Release显式指定，而多配置生成器（Visual Studio、Xcode）是在IDE里选Debug或Release。如果团队里有人习惯用Unix Makefiles，有人用Visual Studio，两边的构建类型机制完全不同，很容易出现"我这边Release是优化过的，你那边Release等于没优化"的乌龙。解决办法是写一个函数封装CMAKE_BUILD_TYPE的处理逻辑，统一入口。

第二个坑在路径处理。CMake的变量里藏着一堆跟平台相关的路径变量，比如CMAKE_INSTALL_PREFIX在Windows上默认是C:\Program Files，在Unix上是/usr/local。如果你在代码里或配置文件里硬编码了安装路径，三端完全对不上。我的做法是：所有路径类的东西都通过CMake的configure_file替换成对应平台的返回值，绝不允许出现在源码里写死绝对路径的情况。

第三个坑是第三方依赖的引入方式。早期我用过add_subdirectory直接把第三方库的源码编进项目，简单粗暴，但会有变量污染、构建顺序混乱的问题。后来切到find_package+FetchContent的组合：能在系统里找到已安装的库就用系统库，找不到就从源码拉取构建，既享受系统包管理的便利，又避免了"用户机器上装不上依赖"的麻烦。

以下是我们在项目里用过的一份比较完整的CMakeLists配置骨架，供参考：

cmake_minimum_required(VERSION 3.20) project(cross_platform_demo CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) if(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Release) endif() find_package(Threads REQUIRED) find_package(OpenCV QUIET) if(NOT OpenCV_FOUND) message(FATAL_ERROR "OpenCV not found, please install it first") endif() add_executable(cross_platform_demo src/main.cpp src/platform_window.cpp ) target_include_directories(cross_platform_demo PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src) target_link_libraries(cross_platform_demo PRIVATE Threads::Threads ${OpenCV_LIBS} ) install(TARGETS cross_platform_demo RUNTIME DESTINATION bin )

3.3 平台相关代码的组织方式

CMake里的多平台条件编译，最怕写成一堆散落的if(WIN32)。我后来用了一个比较规整的模式：平台相关功能抽象成独立源文件，CMake按平台选择编译哪一份。比如窗口创建这块，platform_window.h声明接口，platform_window_win32.cpp、platform_window_linux.cpp、platform_window_macos.mm分别实现，目标文件目录结构保持一致。CMakeLists里这样写：

if(WIN32) target_sources(cross_platform_demo PRIVATE src/platform_window_win32.cpp) elseif(APPLE) target_sources(cross_platform_demo PRIVATE src/platform_window_macos.mm) elseif(UNIX) target_sources(cross_platform_demo PRIVATE src/platform_window_linux.cpp) endif()

好处是平台差异被框在各自文件内部，业务代码只依赖抽象接口，不会因为某个平台的新增逻辑而导致其他平台的编译失败。这套模式后来帮我省了无数维护时间。

4. 平台差异的暗礁：文件系统、动态库与线程

如果说构建系统是跨平台开发的门槛，那平台API差异就是暗礁。这些差异平时看着不起眼，但任何一个都会在运行时给你来一下阴的。

4.1 文件系统与路径：Windows的盘符与Linux的大小写敏感

Windows的文件系统是大小写不敏感的，Linux是大小写敏感，macOS默认不敏感但可以开敏感模式。这意味着同样一套代码，在Windows上创建一个名为Config.txt的文件，在Linux上再去打开config.txt会直接找不到文件。更隐蔽的是路径分隔符，Windows用反斜杠，Linux和macOS用正斜杠，虽然std::filesystem已经帮我们做了大部分转换，但一旦你手动拼接路径字符串（比如拼一个config目录），就会出现混合分隔符的脏路径。

我们封装了一个统一的路径处理函数，强制统一为正斜杠并标准化：

#include <filesystem> #include <string> namespace platform { // 将路径统一为当前平台的标准分隔符，并处理可能的尾部斜杠问题 std::filesystem::path NormalizePath(const std::string& raw_path) { std::string converted = raw_path; #ifdef _WIN32 // Windows下接受正反两种斜杠，但统一输出反斜杠 std::replace(converted.begin(), converted.end(), '/', '\\'); #else // Unix类系统统一输出正斜杠 std::replace(converted.begin(), converted.end(), '\\', '/'); #endif return std::filesystem::path(converted).lexically_normal(); } // 获取用户配置目录，三端路径规则完全不同 std::filesystem::path GetUserConfigDir() { #ifdef _WIN32 const char* buf = std::getenv("APPDATA"); return NormalizePath(buf ? buf : ".\\config"); #elif defined(__APPLE__) const char* buf = std::getenv("HOME"); return NormalizePath(std::string(buf ? buf : ".") + "/Library/Application Support"); #else const char* buf = std::getenv("XDG_CONFIG_HOME"); if (buf) { return NormalizePath(buf); } const char* home = std::getenv("HOME"); return NormalizePath(std::string(home ? home : ".") + "/.config"); #endif } } // namespace platform

这段代码看起来简单，但它解决的是跨平台开发里最容易踩的"路径三兄弟"问题。APPDATA、XDG_CONFIG_HOME、HOME分别是三端用户配置目录的环境变量，取错任何一个，你的程序都会把配置文件写到完全错误的位置，然后表现为"程序重启后配置丢失"这种极其难排查的bug。

4.2 动态库：从导出宏到运行时搜索路径

动态库导出符号这块，Windows和Unix完全是两个世界。Windows用__declspec(dllexport)和__declspec(dllimport)来控制符号的导出和导入，而Linux和macOS使用GCC/Clang的__attribute__((visibility("default")))机制，默认隐藏所有符号，需要手动标记对外可见的那部分。

正确做法是封装统一的导出宏：

#if defined(_WIN32) #if defined(MYLIB_EXPORTS) #define MYLIB_API __declspec(dllexport) #else #define MYLIB_API __declspec(dllimport) #endif #else #define MYLIB_API __attribute__((visibility("default"))) #endif class MYLIB_API SomeExportedClass { /* ... */ };

除了编译期导出，运行期的动态库搜索路径差异也经常背锅。Windows会优先在可执行文件目录找DLL，然后是系统目录和PATH；Linux默认找LD_LIBRARY_PATH，但现代Linux桌面环境对安全比较敏感，很多场合下LD_LIBRARY_PATH会被清空；macOS的@rpath机制又不一样。最省事的方式是：尽量用CMake的target_install和install_name_tool把动态库的安装路径写好，并保证可执行文件和依赖库安装在同一目录下。不要依赖环境变量做运行时搜索，那是所有平台里最不靠谱的方案。

4.3 线程与同步：跨平台下的"假共性"

std::thread和std::mutex是标准库提供的跨平台接口，用起来很舒服，但接口跨平台不等于行为跨平台。Windows的线程调度默认是时间片轮转式，Linux的默认调度策略在多数场景下也是时间片轮转，但macOS对主线程的RunLoop有特殊要求。如果你在macOS的主线程里直接std::thread等待一个事件，很可能会跟UI事件循环冲突，导致界面假死。

线程这一块最实际的建议是：尽量避免自己管理原始线程，改用任务调度抽象层。比如用std::async配合std::future做并发任务，或者用更成熟的并发库。跨平台项目里，自己手搓线程池确实爽，但搓完之后每个平台的调度参数、栈大小、信号处理都够你折腾一周。把并发模型统一到标准库或成熟第三方库，让平台差异被库作者消化掉，是更高性价比的选择。

5. 跨平台GUI与第三方库选型：一次选错，重构半年

我见过太多项目在GUI框架这一环上拍脑袋决定，结果业务写了一大半才发现框架在某个平台上有致命问题，被迫推翻重来。跨平台项目里，GUI选型直接决定了你的开发周期上限。

5.1 GUI框架对比：Qt、FLTK、原生封装、WebView

我把真实碰过的主流方案列了个表，分别讲一下适用场景和局限性：

以我自己的项目为例，最终选了Qt。原因不是Qt最好，而是在"三端一致的外观、平板缩放支持、复杂控件需求"这三个硬指标上，Qt是唯一一个不用我再造轮子的方案。FLTK轻归轻，但我在窗口缩放和复杂表格这块试过，明显要自己补的东西太多。原生封装方案我没选，是因为我们团队同时维护三套原生UI的边际成本承受不起。

5.2 非GUI库的选型逻辑：能用标准库就不引第三方

GUI确定了之后，其他第三方库的选型逻辑就清晰了：能标准库解决的原则上不上第三方库，必须上第三方库时优先选三端支持且API稳定的。

• JSON解析：库的选择很多，我最后用了一个模板驱动的header-only库，因为它在三端的编译方式和行为完全一致，不用额外处理动态库链接问题。有一点值得注意：header-only库在跨平台项目里有天然优势，因为它不存在"DLL Hell"问题。
• 网络通信：早期用过Boost.Asio，功能确实强，但编译速度慢，而且Boost在Windows和Linux上的构建配置差异不小。后来换了轻量一点的HTTP库，API简洁，支持好，商业许可也友好。如果只是简单的HTTP请求，甚至可以用libcurl加一层极薄封装的方案。
• 数据库SQLite：跨平台能力没得说，唯一要注意的是编译时开启SQLITE_THREADSAFE宏设置为序列化模式（值为1），否则多线程访问同一个连接时会偶发崩溃。
• 打包安装：Windows上可以用NSIS或Inno Setup打安装包，macOS用dmg或pkg，Linux用AppImage或deb。这块没有统一的跨平台工具能一劳永逸，但可以用CMake的CPack模块统一配置打包规则，再分别触发对应平台的打包器。

5.3 为什么有些时候"用标准库＋自封装"是最稳的

有一个经验我觉得特别值得分享：第三方库在跨平台项目里的隐性成本，往往不是它不跨平台，而是它把跨平台问题以一种你没预料到的方式暴露出来。比如某图像处理库在Linux上是动态编译，在Windows上只提供静态库，两边混链时符号冲突问题处理起来非常痛苦。

所以我现在有一个很朴素的判断规则：如果某个功能标准库已经有稳定实现，我就果断用标准库；如果标准库缺这块能力，我在引进第三方库之前会先问问自己："这个库三端是否都维护活跃？API是否在三端行为一致？如果它出了问题，我能不能在两小时内定位是库的问题还是我代码的问题？"有一个答不上来，就换个候选库再考察一遍。这套规则帮我避免了不少"引入了全世界最强的库，却卡在最基本的编译配置上"的窘境。

6. 一套代码在Windows、Linux、macOS上编译发布的完整实战

前面讲的都是策略，这一节我把项目从代码到发布的全链路拆开给你看。这个"某跨平台图像处理Demo"的完整CI流程，我自己在三端每个季度至少完整跑一遍，踩坑经验都沉淀在这里。

6.1 目录结构与CMake组织

项目结构大致是这样的：

├── CMakeLists.txt ├── src │ ├── CMakeLists.txt │ ├── core │ │ ├── image_processor.h │ │ ├── image_processor.cpp │ │ └── thread_pool.h │ ├── platform │ │ ├── platform_window.h │ │ ├── platform_window_win32.cpp │ │ ├── platform_window_linux.cpp │ │ └── platform_window_macos.mm │ └── ui │ ├── main_window.h │ ├── main_window.cpp │ └── image_view.cpp ├── tests │ ├── CMakeLists.txt │ ├── test_image_processor.cpp │ └── test_platform.cpp ├── cmake │ ├── functions.cmake │ └── CompilerWarnings.cmake ├── assets │ └── app_icon.ico └── scripts ├── build_windows.bat ├── build_linux.sh └── build_macos.sh

这里的核心设计意图是：core目录不依赖任何第三方库和平台API，platform目录集中管理平台差异，ui目录只依赖core与platform的抽象接口。这样划分后，代码的跨平台难度就被限制在platform目录内部，core部分可以放心地进行单元测试和逻辑验证。

6.2 三端构建脚本的差异处理

Windows端的构建脚本：

@echo off set BUILD_TYPE=Release set BUILD_DIR=build_win cmake -S . -B %BUILD_DIR% -DCMAKE_BUILD_TYPE=%BUILD_TYPE% cmake --build %BUILD_DIR% --config %BUILD_TYPE% -j 4 ctest --test-dir %BUILD_DIR% -C %BUILD_TYPE% --output-on-failure cpack --config %BUILD_DIR%/CPackConfig.cmake

Linux端的构建脚本：

#!/usr/bin/env bash set -euo pipefail BUILD_TYPE=Release BUILD_DIR=build_linux cmake -S . -B "$BUILD_DIR" -DCMAKE_BUILD_TYPE="$BUILD_TYPE" \ -DCMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic" cmake --build "$BUILD_DIR" -- -j"$(nproc)" ctest --test-dir "$BUILD_DIR" --output-on-failure cpack --config "$BUILD_DIR/CPackConfig.cmake"

macOS端的构建脚本：

#!/usr/bin/env bash set -euo pipefail BUILD_TYPE=Release BUILD_DIR=build_macos cmake -S . -B "$BUILD_DIR" -DCMAKE_BUILD_TYPE="$BUILD_TYPE" \ -DCMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic" cmake --build "$BUILD_DIR" -- -j"$(sysctl -n hw.ncpu)" ctest --test-dir "$BUILD_DIR" --output-on-failure cpack --config "$BUILD_DIR/CPackConfig.cmake"

三套脚本的结构高度相似，最重要的细节是：每个平台的并行编译线程数获取方式不同，nproc在Linux上可用，macOS要用sysctl -n hw.ncpu，Windows的bat脚本里没有直接等价命令，我上面直接写死了4。如果两条命令混淆了，构建脚本会在对应平台上直接报错，这种错误在跨平台CI里极其常见。

6.3 CMake编译警告的跨平台一致性

编译警告这块，三个编译器的选项参数长得完全不一样。MSVC用/W4，GCC和Clang用-Wall -Wextra -Wpedantic。为了在三端看到一致的警告输出，我在cmake/CompilerWarnings.cmake里做了统一封装：

function(target_enable_strict_warnings TARGET) if(MSVC) target_compile_options(${TARGET} PRIVATE /W4 /permissive-) else() target_compile_options(${TARGET} PRIVATE -Wall -Wextra -Wpedantic) endif() endfunction()

这里有一个很微妙的地方：/permissive-这个MSVC选项是我后来才加上的。它强制MSVC遵循更严格的标准一致性，否则很多标准没明确定义的行为在MSVC上是"通过"，但换到GCC或Clang上就变成编译错误。不要在IDE里手点这个选项，一定要写进CMake配置里，否则换个人拉代码编译行为就变了。

6.4 发布包里的平台特定文件

发布阶段还有一堆平台相关的"小尾巴"。Windows上需要收集运行所需的DLL（尤其是Qt的插件和平台插件），Linux上要处理RPATH或RUNPATH来保证动态库搜索路径正确，macOS要用macdeployqt或install_name_tool修改动态库的安装名。这些步骤在代码里不会体现，但每个平台的发布物缺一个文件，用户那边就是闪退或白屏。

我现在的流程是：Windows用CMake的install()规则把运行期依赖都带进安装目录，然后用windeployqt补全Qt相关DLL；Linux打deb包时把RPATH设置为$ORIGIN（让程序从自身所在目录找动态库）；macOS用install_name_tool -change把依赖库路径改成@rpath相对路径。每一端都有对应的自动脚本，会跟着CI每次发布跑一遍，避免"人为忘带文件"这种低级失误。

7. 排查跨平台问题的一条高效路径

跨平台开发最耗时的环节往往不是写代码，而是排查"只在某个平台出现"的bug。有个高效排查方法想分享给你：永远先问"这是编译期问题，还是运行期问题？"，然后分路径处理。

7.1 编译期问题：多平台编译矩阵才是最佳过滤器

如果程序在某个平台编译失败，先在CI上完整跑一遍三端编译矩阵，看看问题是否只在某一端出现。只在一端出现的编译问题，多半是平台相关代码写得不干净（比如要用#ifdef _WIN32处理平台头文件但漏了其他平台的对应分支），或者是某个第三方库在该平台上的配置不一样。

我有个习惯：每提交一笔代码，第一个动作就是触发CI三端编译，而不是等本地写完才集中编译。因为很多平台差异只在另一套编译器下才暴露，本地环境往往只能覆盖一个平台。早期的CI工具链不如现在便利时，我喜欢提前用"编译器交叉验证"的方式把问题扼杀在提交阶段——比如在Windows上开发，但会额外用Clang做一次强制编译检查，因为Clang在Linux和macOS上的行为一致性高一些。

7.2 运行期问题：隔离变量是最高效的手段

运行期问题分两种。一种是"每个平台都出现但表现不同"，这种基本是业务逻辑或数据模型设计问题，跟平台关系不大。另一种是"只在某个平台出现"，比如同一个图像处理算法在Windows上正常、macOS上结果偏色。遇到这种，我的排查顺序是：先看标准库API在不同平台上的返回差异，再看第三方库的构建配置是否一致，最后才怀疑自己的算法逻辑。

举个例子，我们项目有个典型的"只在macOS上崩溃"的bug：同一段图像编码函数，调用时传入的buffer指针在Windows和Linux上都没问题，到macOS上偶发段错误。排查到最后发现是macOS对内存对齐的要求比其他平台更严格，那段代码里用了未对齐的指针做强制类型转换，GCC在Linux上能容忍，Clang在macOS上就直报-Wcast-align的问题。这种问题不通过三端编译告警对比，是很难定位的。

7.3 日志系统的跨平台设计：让问题可复现而不是靠猜

跨平台bug的另一个痛点是日志格式不统一，不同平台的日志混在一起，排查时很难对得上时间线。我在项目里设计了一套简单的日志格式化函数：每个日志条目统一包含时间戳（UTC毫秒级）、平台标识（Win/Lin/Mac）、日志级别、函数名、行号、消息。这样在聚合日志时，同一个操作在三个平台上的执行路径可以精确对齐，差异一目了然。

日志这部分最重要的建议是：不要用printf裸奔，一定要走抽象接口，方便在各平台统一接入系统日志（Windows事件日志、Linux syslog、macOS unified log），否则排查线上问题时，你手头会没有任何有效线索。

8. 从"能用"到"好维护"：跨平台抽象层的设计复盘

最后聊一个稍微进阶一点的话题。很多项目开始也能三端跑通，但业务一复杂就乱，根因都在抽象层的设计上。

8.1 两个让我少踩很多坑的设计原则

我自己在这块最大的复盘收获是两条原则：

第一条，核心逻辑绝不依赖平台宏。平台宏（_WIN32、__APPLE__）只允许出现在platform目录里，core目录和ui目录里的代码一旦出现#ifdef _WIN32，就是设计失败的信号。业务代码里看到平台宏，就意味着同样的逻辑在三个平台会走三个分支，测试成本和维护成本都会失控。

第二条，接口粒度以"需求"为准，不以"平台API"为准。比如"获取用户配置目录"这个需求，在Windows上对应APPDATA，在Linux上对应XDG_CONFIG_HOME，在macOS上对应HOME/Library/Application Support。如果接口直接暴露"获取环境变量APPDATA"，那么这段代码就绑定死了Windows。而"获取用户配置目录"这个抽象，才是三个平台都真正需要的能力。

8.2 如何测试跨平台代码

跨平台代码测试分配比也很重要。core目录里的逻辑和平台无关，用普通的单元测试就能覆盖；platform目录的代码因为依赖具体平台API，最好在对应平台各跑一遍冒烟测试；ui目录用自动化截图对比来发现跨平台渲染问题。

我们的冒烟测试脚本会直接在CI上跑三端，检查并验证：合法输入能被正确处理、非法输入不会导致进程崩溃、配置文件能正常生成和读取、程序能启动和退出。每个平台只要这一小套冒烟测试全绿，基本可以放心进入业务功能验收阶段。

8.3 跨平台开发中"默认值"的文化差异

写代码时还有一个比较隐蔽的点：不同平台用户对"默认值"的期待很不一样。比如程序自动保存频率，Windows用户偏向高频保存防止系统更新强杀进程，macOS用户偏向靠系统的自动保存机制，Linux用户则可能完全依赖程序自身。这些不是技术问题，但会影响到你在ui层的默认配置设计。如果完全不考虑这一点，做出来的东西在三端都能运行，但用户会觉得"哪里怪怪的"。

再比如路径分隔符的显示。Windows用户习惯看到C:\Program Files\App\，Linux用户习惯/opt/app/，macOS用户习惯/Applications/App.app/。如果程序里有个"打开配置文件夹"的功能，你写死一种显示格式，另外两端的用户就会觉得这个软件"是给别的系统的人用的"。这种细节上的平台适配，才是跨平台开发从"能用"走向"好用"的分水岭。

9. 跨平台开发最值得投入的几件事

做了这个项目后，我对C++跨平台开发最大的感受变了：它不是"写代码"层面的挑战，而是"做设计"层面的长期取舍。如果让我给刚入坑的人排序，最值得投入时间的三件事是：

第一，把CMake构建配置打磨成一套基础设施。跨平台项目后续所有的省心，都来自前期构建系统的规范程度。你花一个周末把CompilerWarnings.cmake、依赖管理、打包脚本写好，后面整个开发周期都在享受这套基础设施的红利。

第二，给所有平台差异装一道"闸门"。平台相关的代码隔离进独立目录，主业务代码看不到#ifdef。初期多花一点抽象成本，中后期业务复杂后你会感激这个决定的。

第三，CI的三端编译矩阵尽早配起来。不要等代码写差不多了才想着怎么发布，从第一个commit开始就三端跑编译和冒烟测试，跨平台问题应该在它最便宜的时候被修复——也就是刚提交的那一刻，而不是上线前夕。

我在实际开发中还有一个屡试不爽的习惯：开发机上永远留一份Linux交叉编译环境。哪怕主力系统是Windows，也会在本地容器里跑一遍Linux编译检查，因为编译器告警在三个平台上的响应速度差异很大，早点看到GCC的报错，就能早点意识到"这段代码在另一个平台上也是这么写的，现在必须修正"。有人觉得多此一举，但踩过"Windows编译零警告、Linux编译直接失败"坑的人都会明白它的价值。

跨平台开发没有"一招鲜"，但把构建系统做规范、把平台差异装进闸门、把CI当日常，剩下的就是业务本身的事了。希望这篇复盘能帮你少走一些我走过的弯路。