王杰岸1. 在 Arch 上折腾 OneDrive 的第一个岔路口：为什么我最后选了 abraunegg
说实话，Arch Linux 生态里的同步备份工具从来不缺，但“想和 OneDrive 保持双向实时同步”这件事，长期以来都处在一种没人真正替你兜底的状态。微软官方 Linux 客户端难产，Rclone 虽然强大却更多是做网盘挂载和单向备份，真要拿它维护一个本地工作目录和高频编辑文件，冲突处理和实时性都不够顺手。我在换了三次方案之后，最终把主力固定在了 abraunegg/onedrive 这个开源客户端上。
这个客户端本质上是一个独立的命令行程序，用 Go 编写，直接对接微软 OneDrive API。它处理的不是“把网盘挂载成磁盘”这种逻辑，而是真正维护一个本地目录和云端之间的双向数据同步。Arch 用户对它应该不陌生，AUR 里的包名是 onedrive-abraunegg。它支持 OneDrive 个人版、OneDrive for Business，也能处理 SharePoint 文档库，但让我下决心长期用的原因其实很简单：监控模式足够稳，sync_list 白名单足够灵活，而且 systemd 集成很干净。
如果你是以下几种情况，这篇文章大概率对你有用：一直在 Arch 上找不到合适的 OneDrive 客户端，或者试过 Rclone 定时任务但处理不了文件冲突；换了新电脑需要把 OneDrive 目录完整落本地；以及手里是工作账号、需要处理 SharePoint 站点同步但不知道该从哪里下手。下面所有内容都基于我在 Arch 环境里的真实部署经验，包括那几次让我差点想放弃的授权报错和同步挂起，都会如实写出来。
先说一个很反直觉的结论：安装这个客户端并不是最麻烦的部分，真正的门槛在你第一次运行它之前的账号判断和目录规划上。 很多人懒得看这一步，直接一把梭开始同步，结果面对几百个文件夹根本不知道哪里出了问题，最后只能骂一句工具不好用。实际上只要你把前置决策想清楚，后面的部署误差会小一大半。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 装之前必须先想清楚的两件事：账号类型和同步目录
2.1 账号类型直接决定参数形态
很多人以为 OneDrive 客户端只要登录就能同步，忽略了 OneDrive 账号本身存在多种形态。客户端的默认流程会去连接 Microsoft 全球版端点，但如果你使用的是由组织分配的 Business 账号，或者挂在 SharePoint 站点下，初始化后可能看不到任何数据，大概率就是账号类型判断错了。
在开始配置之前，先确认你的账号属于哪种：
| 账号类型 | 常见特征 | 需要注意的点 |
|---|---|---|
| OneDrive 个人版 | 以个人微软账号登录 | 基本无需额外参数，同步根目录就是网盘根 |
| OneDrive for Business | 组织分配的 O365 账号 | 可能需要确认 API 端点类型，部分旧租户有差异 |
| SharePoint 文档库 | 从组织站点进入 | 需要先把目标站点路径加到同步配置里，否则扫描不到 |
这个区分不是玄学，而是客户端在启动时会对账号类型做探测，然后决定它默认访问哪个数据源。个人版通常就是一帆风顺，但 Business 账号在首次运行后会打印出一长串调试信息，里面会出现站点、Drive ID 之类字样。当时我一度以为客户端坏了，后来用 onedrive --display-running-config 看输出，才发现它根本没找到预期的同步内容。
提示：如果你运行后输出的配置里
account_type不是你预期的类型，别急着开--resync。先在终端用onedrive --verbose --dry-run跑一次，看日志里探测到的数据源信息，再决定后面怎么配置。
2.2 目录布局：别把同步目录塞在系统盘根路径
客户端默认会创建 ~/OneDrive 作为本地同步目录。听起来没什么问题，但 Arch 用户通常有自己的目录洁癖——有人希望把同步内容放在独立的数据盘或独立分区上，有人则希望把不同类型的文件拆成多个同步目录。
有一个很关键的配置项是 sync_dir，它控制本地同步根目录。这个路径千万别随手写成 /home/user/OneDrive 然后不管了，因为后续你会涉及 sync_list 白名单、skip_file 排除规则，这些规则全是相对这个根目录来解析的。路径一旦中途想改，历史数据库需要重建，等于重新做一次全量比对。
如果机器上有多个网盘要同时维护，我建议规划成类似这样：
/data/sync/onedrive—— 个人工作文档/data/sync/onedrive_business—— 公司项目资料/data/archive—— 不参与同步的历史归档
同一个账号在同一台机器上其实可以起多个实例，只需为每个实例单独指定配置目录，但那是进阶玩法，新手期不建议碰。先保证一个账号对应一个同步目录并且路径固定，能省掉大量认知负担。
2.3 编译期依赖
如果你打算用 AUR 安装，依赖会被自动拉好。但如果你想手动编译，或者 AUR 构建时出错需要自查，至少得知道这个客户端真正依赖什么。
运行时依赖包括 curl、sqlite 和 glibc，客户端用 SQLite 在本地维护一个文件状态数据库，用 libcurl 发 API 请求。编译阶段需要 go 工具链、make、git，以及编译 SQLite 绑定可能会用到的 pkg-config 和头文件。Arch 的 base-devel 组通常已经把 make、pkg-config 带上了，真正容易漏的是 go 版本太旧或缺失。
code复制sudo pacman -S --needed base-devel git go curl sqlite
这些依赖装齐之后，无论是走 AUR 还是手动源码编译，基本都不会卡在环境问题上。
3. 三种安装路径实测：AUR、源码编译和后续版本核验
3.1 AUR 安装：最省事但不代表零问题
如果你是 Arch 老用户，大概率会直接上 AUR 助手。我个人的操作是用 yay，命令非常简单：
code复制yay -S onedrive-abraunegg
这个包会从 GitHub 拉源码，在本机完成构建，然后安装二进制文件、man 手册、示例配置以及 systemd 服务单元。实测正常情况下整个构建过程大约几分钟，取决于机器性能。
AUR 有一个常见的小坑：当上游依赖升级或 PKGBUILD 里的校验和与上游 tag 不一致时，构建会中断。报错通常在 validpgpkeys 或 source 校验阶段。遇到这种问题，先在 AUR 页面看评论区，维护者通常会在几个小时内更新 PKGBUILD；如果急用，可以临时把校验和相关的 SKIP 值改掉，但安装后最好留意后续更新，因为 tarball 校验是安全防线，不建议长期关闭。
3.2 源码编译：适合需要自定义或者排查构建问题的场景
AUR 不可用的罕见情况下，可以手动编译。这也能帮你理解整个客户端的构成，排查问题时更有底。
code复制git clone https://github.com/abraunegg/onedrive
cd onedrive
make configure
make
sudo make install
make configure 会检查依赖并生成构建配置，如果缺了什么会明确提示。编译出的二进制默认会装到 /usr/local/bin/onedrive，配置文件模板和 systemd 文件也会一并安装到对应目录。
手动编译还有一个额外好处：如果你想测试最新 master 分支的新特性，直接从源码切分支再编译即可。AUR 路径在版本发布节奏上天然滞后一些，毕竟维护者要等上游 release 打 tag。
注意：无论是 AUR 还是源码编译，安装完成后不要急着直接运行。先执行一次
onedrive --version，确认二进制能正常加载库。如果这里就报动态库缺失，多半是编译阶段依赖不完整，回头补齐再重编。
3.3 安装后的文件分布与示例配置
装完以后我习惯先看一遍文件分布，这对接下来的排错很有帮助：
- 二进制位置：
/usr/local/bin/onedrive或/usr/bin/onedrive - systemd 用户服务：
/usr/lib/systemd/user/onedrive.service - 配置文件模板：通常处于
/usr/share/doc/onedrive/或包安装路径下，里面有config示例文件
配置目录默认在 ~/.config/onedrive。第一次运行生成授权信息后，目录下会多出 config、sync_list（如果创建了的话），以及用于存放授权 token 的缓存目录。后面排查登录问题时，token 缓存经常是重点嫌疑对象，我们要知道它在哪里。
4. 首次授权那十分钟：最容易让人以为客户端坏了的地方
4.1 浏览器授权与终端回调的完整链路
安装好后，直接运行 onedrive，程序会先初始化配置并检测是否已经存在授权 token。干净的机器上它会打印一个授权 URL，同时在本地起一个临时 HTTP 服务等待回调。
实际操作时，你需要把终端里那串很长的 URL 完整复制到浏览器，登录你的微软账号，选择要授权的权限。当浏览器界面显示“可以关闭此页面”之类的提示后，本地客户端会收到回调，然后继续执行首次同步扫描。
逻辑上并不复杂，但你可能会遇到几个问题，这里重点说两个。
第一个是终端显示的 URL 太长，复制时被截断。用鼠标在某些终端里拖动选择很容易只选到一部分，导致浏览器报错。我习惯用 shift+点击 或直接让终端输出到文件再打开。更稳妥的做法是运行客户端时加上 --auth-uri 参数，它只负责输出授权 URL，不会同步启动全量扫描，等授权完成后再另行启动正式同步，流程会更清晰。
第二个问题是浏览器回调地址被拦截。授权完成后浏览器会尝试访问 http://127.0.0.1:端口/callback?code=... 这样的本地地址。如果你用的是 Firefox 并且开了比较严格的反跟踪策略，或者系统里默认浏览器在 localhost 访问上有异常，页面可能会显示拒绝访问或无法连接，但这不代表授权失败。此时有两个办法：如果终端还在等待回调，直接把浏览器地址栏里完整的 http://127.0.0.1:... 地址复制回终端粘贴进去；如果服务已经超时，重新运行一次授权流程即可。
4.2 token 到底存在哪里，为什么出了授权问题先找它
授权成功的标志是客户端能够访问你的云端数据，而这个“访问资格”通过 OAuth token 体现。token 文件被存放在缓存目录下，不同版本略有差异，常见位置是 ~/.cache/onedrive/。如果你重复授权了几次依然失败，或者明明在网页上点了授权但客户端还是报未授权，一个很有效的排错手段是：
- 先完全退出正在运行的 onedrive 进程
- 删掉缓存目录里的旧 token 文件
- 重新执行授权流程
这个操作等同于让客户端忘掉以前的所有登录状态，从零开始。千万不要在授权流程进行到一半时手动删文件，那会导致状态错乱。尽量在一次干净流程内完成授权。
4.3 授权成功后的第一个动作：先干跑而不是直接全量同步
这是我想重点强调的一个经验。授权完成后，如果你直接不加参数运行 onedrive，它能给你同步成百上千个文件。但如果中间有任何一个文件因为命名、路径长度或权限问题卡住，整个同步进度就会打折扣，排查起来非常痛苦。
比较好的做法是授权完成后先跑一次干跑模式：
code复制onedrive --dry-run
这个模式会扫描云端和本地目录，把所有“将要上传”“将要下载”“将要删除”“发生冲突”的动作打印出来，但不会真正执行。通过这次干跑，你能快速看出客户端对目录结构的理解是否符合预期。比如云端某个大文件夹是否被忽略了，本地某个不存在的目录是否会被新建，都能提前发现。确认输出合理后再正式同步，能避免很多拍脑袋式的问题。
5. 配置文件里的门道：sync_dir、skip_file 和 sync_list 的配合
5.1 默认配置不是最优配置
客户端在没有配置文件时也能运行，它会直接用内置默认值：同步目录为 ~/OneDrive，全部云端内容都在同步范围内，排除规则是一组内置的系统临时文件模式。
但实际使用中，默认配置几乎总是要改的。要么是同步目录想放在其他位置，要么是某个账号下面同时挂着个人目录和团队站点，全量同步不现实。这时候就需要 ~/.config/onedrive/config 文件登场。
官方会在安装路径下提供一份完整的 config 示例，字段非常多，但不建议第一次就全部照抄。我最常用的几个字段只有这些：
code复制sync_dir = "~/OneDrive"
skip_file = "~*|.~*|*.tmp|*.swp"
sync_root_files = "true"
skip_file 用的是正则风格，用 | 分隔多条规则，匹配的文件会被客户端排除在同步操作之外。临时文件的过滤非常重要，如果你用 VS Code 或 vim 编辑文件，各种临时交换文件一旦被同步到云端，纯属制造噪音。sync_list 的语法不在这里，它是单独的一个文件，别和 config 混在一起。
5.2 sync_list 的实质是白名单，不是简单的“过滤”概念
很多人很容易被 sync_list 的名字迷惑，以为它只是一个“可以选择同步哪些目录”的列表，甚至觉得自己可以用它做黑名单，把不想同步的东西塞进去。这个理解是错的。
官方文档里讲得很清楚，sync_list 一旦存在，客户端就会以它为基准构建“可见的云端文件树”。没有出现在 sync_list 中的目录，客户端在扫描阶段就根本不会纳入同步范围，即使是 skip_file 的优先级也只作用于已经纳入范围的文件上。
所以 sync_list 更像是“我只关心这些目录”的声明。目录格式上，如果 sync_list 文件不存在，客户端同步云端全部；文件存在时，格式类似于：
code复制# 这是注释，用 # 号开头
Documents/
Photos/
Projects/Archive
每一行是相对于 OneDrive 根目录的路径。你可以不带 / 前缀，只要目录名没有歧义即可。支持通配符，比如 Documents/*/图片 可以匹配 Documents 下一层目录中名为“图片”的文件夹。
有两点要注意：
第一，sync_list 里写目录名时的层级关系一定要和你云端实际的路径对得上。如果云端根目录下根本没有 Documents 这一层，那列表就匹配不到任何内容，结果表现为同步目录里什么都不出现。这时先用网页版看一眼云端根级有哪些目录，再回头填 sync_list。
第二，sync_list 修改之后，实际效果的生效常需要一个重建动作。如果你已经正常同步过一段时间，然后往 sync_list 里新增了一个目录，客户端不会立刻自动发现这个新目录并同步。这里就需要在 onedrive --sync 时使用 --resync 清理数据库中旧的索引状态，让它重新对齐一次。但 --resync 绝对是个优先推荐谨慎使用的开关，因为它意味着客户端要重新校验所有已同步文件的状态，文件多的时候相当于重新做一遍全量比对。生产目录中频繁使用它并不是好习惯。
5.3 什么时候用 skip_file，什么时候用 sync_list
我自己的判断标准很简单：
- 如果同步目录里只有少数几个特殊文件/文件夹需要排除，用
skip_file和skip_dir。 - 如果云端目录极其庞大，而本地只需要其中一小部分，用
sync_list限定范围。
有用户会遇到本地出现一个名为 .hidden 的目录，里面放着一堆不想被上传的密钥。这种需求用 skip_dir = ".hidden" 比 sync_list 写白名单要合理，因为 sync_list 白名单一旦启用，默认连云端根目录下新增的未列目录都不会同步，反而容易导致你遗漏新文件。
6. 长期稳定运行的终章：systemd 监控服务与实战排错
6.1 监控模式不是轮询，是事件驱动
客户端有一个 monitor 模式，运行后会一直驻留后台，监听本地同步目录的文件事件。任何新增、修改、删除操作都会被 inotify 捕获并触发上传或删除动作；同时它也会定期轮询云端，拉取远端的变更。
这个“事件驱动 + 轮询兜底”双通道设计是它比单纯定时任务（比如 cron 每天跑一次 Rclone）更适合作为主力同步工具的原因。定时任务只能保证周期一致性，而你白天高频改文件时，另一台设备上可能已经出现了版本差异。monitor 模式在文件保存后的几十秒内就会把变更推上去，体验上和 Dropbox 这类原生客户端非常接近。
6.2 用 systemd 用户服务把它钉在后台
直接在终端里跑 onedrive --monitor 当然可以，但 Arch 上更优雅的做法是利用安装时自动带上的 systemd 用户单元。
启用方式：
code复制systemctl --user enable --now onedrive.service
查看运行状态：
code复制systemctl --user status onedrive.service
journalctl --user -u onedrive.service -f
用 user 服务而不是系统服务的好处很明显：不需要 root，日志和配置都落在普通用户目录下，开机后只要用户会话活跃它就能自启。桌面环境里 systemd 用户实例默认随着 login session 启动，所以如果你平时习惯开机后自动登录桌面，这个服务基本可以做到开机即同步。
我建议第一次启用后，花两分钟看一眼最新日志。正常的日志应该出现类似“扫描中”“上传了 xxx”“监听到变更”等描述。如果日志完全空白，大概率是服务根本没有跑起来，用 journalctl -u onedrive.service -n 50 查看启动错误。
6.3 排错实录：授权超时、99% 同步卡住、永久冲突
下面这几个问题是我实际踩过且后来反复被社区里其他用户遇到的，逐个记录下来供你参考。
授权时浏览器已经提示成功，但客户端迟迟没反应。 这种通常是本地回调端口被某种网络策略挡了。我当时的处理是重启一次授权流程，在浏览器完成授权后观察终端。终端所在网络如果开启了比较激进的本地代理规则，可能导致 localhost 回调被吞掉。如果反复出现，先确认系统代理配置是否对本地地址有例外规则，而不是急着重装客户端。
同步进度卡在 99% 或者日志里反复出现某个文件的 HTTP 错误。 大型目录首次同步时常发生。这时候不要反复重启客户端，因为它会重新发起扫描请求，反而容易触发服务端的限流。正确的做法是先看 journalctl 里被卡住的文件路径，多半是文件名带特殊字符、路径过长或者本地权限不足。手动处理完该文件，再继续等待监控模式自己恢复。
一个文件出现在两个地方，名字带 “conflict” 后缀。 这是客户端的冲突处理机制。当检测到本地和云端在同一段时间内被修改产生版本分叉时，它会保留较新修改的一个版本，另一个文件重命名为带冲突标记的文件，而不会静默覆盖任何一方。这是正确且安全的行为，但如果你不想频繁看到冲突文件，最好养成“同一时间尽量在一台设备上编辑同一批文件”的习惯。它不是一个 bug，而是一种保护。
账号在线但同步目录里总是缺少部分文件。 优先检查 sync_list 是否遗漏目录；其次检查该文件在云端是否是 SharePoint 站点内而不是个人目录下。不同的数据源对应不同的配置路径，个人网盘里看不到不是异常。
6.4 性能调优：针对大型 OneDrive 的建议
如果云端文件数量达到数万甚至几十万级别，客户端会消耗较多内存和 CPU。日常操作层面我最推荐的调优手段是：
- 用 sync_list 缩小需要关注的文件范围，这是最立竿见影的做法。
- 确保本地同步目录和工作目录分离，避免客户端在同一目录上监控其他程序产生的海量临时文件。
- 非活跃的大文件目录可以改用按需同步的模式，而不是全部落在磁盘上。abraunegg 客户端支持
--download-only这类参数，配合 sync_list 可以做到“本地只保留需要的结果，不需要的云端文件不产生本地副本”。这和真正意义上的占位文件不完全相同，但在控制磁盘占用上非常实用。
6.5 升级与维护：多给自己留一条回滚的路
最后聊一个维护习惯。Arch 是滚动更新系统，AUR 包也会频繁跟随上游版本迭代。升级客户端后，最好先执行一次：
code复制onedrive --display-running-config
确认加载的配置路径、账号类型和 sync_dir 没变。然后看看服务是否还活着，没有报 schema 版本之类的错误。数据库结构如果发生变动，新版一般会自动迁移，但总有无法完全平滑的风险。万一升级后出现数据库格式不兼容，删除缓存目录下的数据库并重建虽然能解决，但代价是需要重新扫描比对，相当于重新建立索引。
因此在每次大版本升级前，如果你对当前同步状态很满意，可以先花一分钟把配置目录备份一下。配置不重，但备份后心里有底。实际运维中这份备份救过我一次，所以习惯一直保留到这里。
对我来说，这个客户端最值得称道的地方，始终是它把复杂度控制得相对透明。所有状态都能在日志里找到，所有目录决策都摆在配置文件中，发生什么事都能查到一个出处。这种可控感，恰恰是很多人从其他方案转过来之后不愿意再回去的原因。