MacBook 与 iPhone 之间同步 Logseq 笔记的两种方案

背景

Logseq 是一款基于本地文件的隐私优先笔记工具，所有数据以 Markdown 文件存储在本地目录。这种设计带来了极高的数据掌控力，但也引入了一个现实问题：如何在多设备之间同步这些文件？

我的使用场景是：

MacBook 是主力设备，日常编辑笔记，笔记目录同时是一个 Git 仓库（/Users/stone/git-code/logseq-hub）
iPhone 用于随时查看笔记，偶尔需要在外出时阅读

Logseq 官方提供了付费的同步服务，这里只讨论基于Git + iCloud的免费解决并比较它们的优缺点。

为什么 Logseq 的 Git 插件不能在 iPhone 上用？

在深入方案之前，先解释一个常见误区：为什么不能直接在 iPhone 上用 logseq-plugin-git 插件同步？

logseq-plugin-git 是 Logseq 社区开发的一款插件，在桌面端可以方便地执行 git commit / push / pull 操作。它的核心原理很简单——在 Logseq 内部调用系统 git 命令行工具：

1	Logseq 插件 → 调用 /usr/bin/git → 执行 commit/push/pull

这在 macOS、Windows、Linux 上没有问题，因为系统自带 git。但在 iOS 上完全不可行，原因有三层：

1. iOS 没有自带 git

iOS 系统的 ROM 里根本没有 git 二进制文件。与 macOS 不同，iOS 不提供系统级的命令行工具。

2. iOS 不允许 App 调用外部进程

iOS 的安全模型规定，每个 App 运行在独立的**沙盒（Sandbox）**中，只能访问自己目录下的文件，不能 fork/exec 外部命令。即使系统里有 git，App 也无法像 macOS 那样通过 Process() 启动一个外部进程。

3. Logseq iOS 插件能力受限

iOS 版 Logseq 的插件运行在受限的 WebView / JS context 中，没有 Node.js 环境的 child_process API，无法执行 shell 命令。

能力	macOS	iOS
系统自带 git	✅	❌
App 可调用外部命令	✅	❌
插件可执行 git	✅	❌

核心原因是 iOS 的安全模型不允许 App 调用系统命令行工具，这是 Apple 有意为之的设计。因此，在 iPhone 上实现 Git 同步，需要
、、借助外部工具。

方案一：Mac → iPhone 单向同步（iCloud + 增量复制）

思路

在 MacBook 上维护 Git 仓库作为唯一数据源，通过定时任务将笔记内容增量复制到 iCloud 中 Logseq 的专用目录，iPhone 端的 Logseq App 自动从 iCloud 读取数据。

Git 仓库（Mac 本地）         版本控制，日常编辑
      ↓ 每天 18:00 增量同步
iCloud Logseq 目录            只包含笔记内容，不含 .git
      ↓ iCloud 自动同步
iPhone Logseq App             只读浏览

实现方式

1. 同步程序

用一个轻量的 Swift 程序实现增量复制，核心逻辑：

遍历源目录，跳过 .git 和 .DS_Store
逐文件比较源和目标的文件大小和修改时间
只有变化的文件才会被复制，未修改的文件跳过
复制后同步源文件的修改时间属性
每次运行输出日志，记录复制了多少文件、跳过了多少

关键设计：刻意跳过 .git 目录。这样 iCloud 只同步笔记内容文件，不会同步 Git 内部数据，避免了 iCloud 对 .git/ 下大量小文件的同步导致的性能问题和仓库损坏风险。

2. 定时任务

用 macOS 的 LaunchAgent 实现定时调度，配置文件位于 ~/Library/LaunchAgents/com.stone.sync-logseq-icloud.plist：

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>18</integer>
    <key>Minute</key>
    <integer>0</integer>
</dict>

每天 18:00 自动触发同步，用户无感知。日志输出到 ~/Library/Logs/sync-logseq-to-icloud.log，方便排查问题。

3. iPhone 端

无需任何配置。只要 iPhone 登录同一 Apple ID 且开启 iCloud Drive，Logseq App 会自动识别到 iCloud 中的图谱目录，打开即可浏览。

优点

Git 仓库无冲突风险：Git 仓库和 iCloud 目录完全隔离，Git 操作不会触发 iCloud 同步，iCloud 也不会反向修改 Git 仓库
避免 .git 目录同步：增量复制程序刻意跳过 .git，iCloud 只同步笔记内容文件，不会因为大量小文件同步导致性能问题或仓库损坏
数据一致性好：单向同步意味着只有一个数据源（Mac 上的 Git 仓库），不存在双向冲突的问题
零配置：iPhone 端不需要安装任何额外 App，不需要配置 git，不需要手动操作
运行稳定：LaunchAgent 是 macOS 原生机制，比 crontab 更可靠，开机自动加载

缺点

单向写入：只能在 Mac 上编辑，iPhone 端只能查看。如果在 iPhone 上编辑了笔记，修改不会回传到 Mac，下次同步时还会被覆盖
不实时：定时任务每天 18:00 执行一次，白天在 Mac 上写的笔记，iPhone 上要等到晚上才能看到。虽然可以修改定时同步频率，但不够实时
依赖 iCloud 存储：笔记内容会占用 iCloud 存储空间，如果笔记较多（尤其是含图片附件），可能需要购买更多 iCloud 空间

方案二：使用 iSH 和 Git 直接同步

思路

在 iPhone 上安装 iSH（一个 iOS 上的 Linux 模拟器），在其中安装 git，直接 clone 远程仓库到本地。通过 iOS「文件」App 的共享机制，让 Logseq 打开 iSH 管理的仓库目录，实现双向同步。

GitHub 远程仓库
      ↕ git push/pull
Mac（Git 仓库）          日常编辑，自动 commit & push
      ↕ git push/pull
iSH（iPhone 本地 clone）  通过 iOS 文件共享
      ↕ 直接读取
Logseq App（iPhone）      编辑后通过 iSH push 回远程

实现方式

1. 安装 iSH 和 git

本质是一个 iOS 上的 Linux 模拟器（x86 usermode）。

从 App Store 安装 iSH，打开后执行：

# 修改iSH所在环境的linux repo源，解决apk安装git慢的问题
cp /etc/apk/repositories /etc/apk/repositories.bak

echo "http://mirrors.tuna.tsinghua.edu.cn/alpine/v3.14/main" > /etc/apk/repositories
echo "http://mirrors.tuna.tsinghua.edu.cn/alpine/v3.14/community" >> /etc/apk/repositories

# 安装 git
apk update
apk add git

⚠️ iSH 开始使用时系统”设置“->”App“->”iSH”页面没有看到“本地网络“权限开启项（只有开启”无限数据“->”无线局域网与蜂窝网络”的选项），不能访问外部网络。可以通过iSH中执行命令nc -v -w 1 255.255.255.255 80，显式触发网络权限申请，通过权限后“设置”页就可以看到“本地网络”权限项了。

2. Clone 仓库并挂载到 iOS 文件系统

# 配置ssh连接github环境
apk add openssh-client
ssh-keygen -t ed25519 -C "[email protected]"
# 复制公钥到github账号设置“SSH和GPG Keys“
cat ~/.ssh/id_ed25519.pub

# 将 iOS 文件 App 的目录挂载到 iSH

mount -t ios . /mnt

# Clone 仓库到挂载目录
mkdir /mnt-logseq

# 执行下面命令弹框中绑定“我的iPhone -> Logseq -> Logseq-hub”
mount -t ios . /mnt-logseq

cd /mnt-logseq
git clone https://github.com/你的用户名/logseq-hub.git

挂载后，iSH 和 Logseq 访问的是同一份文件，无需手动复制。

⚠️ 实操过程中iPhone中Logseq加载git拉取后的文件夹时会遇到各种问题。比如异常No permission, please clear cache and re-open graph folder.可以按提示unlink -> Settings (设置) -> Advanced (高级设置) -> “Clear cache” (清除缓存) -> 强制关闭Logseq -> 重新打开加载我的iPhone -> Logseq -> Logseq-hub目录

3. 日常同步流程

# 拉取最新内容
cd /mnt/logseq-hub
git pull

# 在 Logseq 中编辑笔记后，推送修改
git add .
git commit -m "sync from iphone"
git push

4. 自动化（可选）

可以通过 iOS 快捷指令（Shortcuts） 自动化 git pull/push 操作，减少手动操作。也可以将挂载命令写入 iSH 的 .profile 实现自动挂载。

优点

双向同步：iPhone 端可以编辑笔记并 push 回远程仓库，Mac 端 pull 即可获取更新，真正实现多设备双向同步
链路短：直接通过 Git 协议同步，不经过 iCloud 中转，没有中间环节
不占用 iCloud 存储空间：笔记文件存在 iSH 的本地目录或挂载的 iOS 目录中，不经过 iCloud
有完整版本历史：所有变更都有 Git commit 记录，可以追溯和回滚

缺点

需要折腾：从安装 iSH、安装 git、挂载目录到配置自动化，整个流程涉及不少技术细节，门槛较高
iSH 网络问题：iSH 在 iOS 上通过 x86 模拟器运行，网络栈不完全稳定，DNS 解析、网络权限等问题需要逐一排查，国行 iPhone 尤其常见
git 操作需要手动：iSH 中没有 GUI，每次同步需要手动执行 git pull / add / commit / push，虽然可以用快捷指令自动化，但配置本身也是工作量
冲突需要人工解决：如果 Mac 和 iPhone 同时编辑了同一个文件，git merge 冲突需要手动解决，对于笔记场景来说比较繁琐
性能一般：iSH 是 x86 模拟器，git 操作速度比原生慢，仓库较大时 clone 和 pull 会比较慢
挂载不持久：iSH 重启后 mount -t ios 会丢失，需要重新挂载或写入 .profile 自动执行

方案对比

维度	方案一：iCloud 单向同步	方案二：iSH + Git 双向同步
同步方向	单向（Mac → iPhone）	双向
实时性	每天 18:00 定时同步	随时手动 git pull/push
iPhone 端编辑	❌ 不支持	✅ 支持
版本历史	❌ 无	✅ 完整 Git 历史
配置复杂度	低（已配好，零维护）	高（iSH + DNS + git + 挂载 + 自动化）
稳定性	高（LaunchAgent + 增量复制，运行稳定）	中（iSH 网络、挂载、冲突都有不确定性）
iCloud 存储占用	有（同步笔记内容文件）	无
冲突风险	无（单向，唯一数据源）	有（需手动解决 git merge 冲突）
适合场景	Mac 为主力，iPhone 只读浏览	多设备都需要编辑