最可靠方式是Windows用SHGetKnownFolderPath获取FOLDERID_Documents，macOS/Linux用getenv("HOME")拼接"Documents"；禁用CSIDL、QStandardPaths和current_path，路径拼接须用std::filesystem::path。
Windows 用 SHGetKnownFolderPath，别碰 CSIDL
Windows 上最可靠的方式是调用 SHGetKnownFolderPath 获取 FOLDERID_Documents，而不是过时的 CSIDL_MYDOCUMENTS（它在某些配置下会返回桌面或重定向失败）。CSIDL 系列 API 在启用了“文档库”或 OneDrive 文件夹重定向时行为不稳定，且 Win10/11 已明确标记为 deprecated。
实操要点：
-
SHGetKnownFolderPath需要链接shell32.lib，头文件是shlobj.h - 必须用
CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED)初始化 COM，否则返回E_FAIL - 返回的路径是宽字符
wchar_t*，需转码（如用std::filesystem::path或WideCharToMultiByte）才能用于普通字符串操作 - 记得调用
CoTaskMemFree释放返回的内存，否则泄漏
macOS 和 Linux 用 getenv("HOME") 拼接 "Documents"
macOS 和 Linux 没有系统级“文档目录”概念，标准做法是取 HOME 环境变量后拼 "Documents"。注意：这不是约定俗成的“建议”，而是事实上的唯一可移植路径——~/Documents 是 Finder、Nautilus、Dolphin 等默认创建并识别的目录，且多数跨平台应用（VS Code、Obsidian）都按此约定查找。
常见错误现象：
立即学习“C++免费学习笔记（深入）”；
- 直接硬编码
"/Users/xxx/Documents"—— 用户名可能含空格或非 ASCII 字符，且无法适配非默认 shell - 调用
getpwuid(getuid())获取家目录 —— 在容器、CI 或某些 macOS 配置下可能失败或返回空 - 忽略大小写：Linux 下
"documents"不等于"Documents"；macOS 默认不区分但 HFS+ 卷可能区分，统一用大写更安全
不要用 QStandardPaths 或 std::filesystem::current_path()
Qt 的 QStandardPaths::writableLocation(QStandardPaths::DocumentsLocation) 看似方便，但它在 Windows 上可能返回重定向后的路径（如 OneDrive），在 Linux 上可能返回 XDG 文档目录（~/.local/share/Documents），而该路径通常为空且不被 GUI 文件管理器识别；std::filesystem::current_path() 则根本无关——它返回的是进程当前工作目录，不是用户文档目录。
性能与兼容性影响：
-
QStandardPaths引入 Qt 依赖，对纯 C++ 项目是冗余开销 - 某些发行版（如 NixOS）或容器环境里，XDG 变量未设置，
QStandardPaths会 fallback 到HOME，但逻辑不透明，调试困难 - 没有理由信任当前工作目录能代表“用户文档位置”，尤其当程序被脚本或 IDE 启动时
路径拼接必须用 std::filesystem::path，别手写 "/" 或 "\"
跨平台路径拼接出错率极高：Windows 用反斜杠，macOS/Linux 用正斜杠，但 std::filesystem::path 会自动处理分隔符归一化和空段过滤。手写字符串拼接容易漏掉斜杠、多加斜杠，或在 Windows 上生成 "C:\Users\Alice\Documents\" 这种结尾带反斜杠的路径——某些 API（如 CreateDirectory）虽容忍，但 std::filesystem::exists 在旧 libstdc++ 上可能误判。
实操建议：
- 统一用
std::filesystem::path home = std::getenv("HOME");（Linux/macOS）或从SHGetKnownFolderPath构造std::filesystem::path - 拼接写成
home / "Documents"，不是home.string() + "/Documents" - 检查存在性前先调用
.make_preferred()，避免路径中混用斜杠风格导致比较失败
真正麻烦的不是获取路径本身，而是后续所有 I/O 操作都得基于这个路径做存在性判断、创建、权限检查——而这些在不同系统上失败原因完全不同：Windows 可能因 UAC 拒绝写入，macOS 可能因 TCC 权限弹窗阻塞，Linux 可能因 umask 导致子目录不可写。路径只是起点，别以为拿到字符串就万事大吉。
