无需云服务，实时同步两台机器间的文件夹。在任何地方保持 dotfiles / 笔记 / 项目完全一致。

同时使用 Mac 和 Windows 的人，迟早都会问：「我今天新建的这个文件，怎么弄到另一台机器上？」 U 盘、Dropbox、iCloud、OneDrive、Git、SCP——每种方式都有明显缺陷。云服务有容量限制和隐私顾虑；Git 不适合二进制文件和中间产物；SCP 缺乏自动化。

我认为文件同步的选择不应该是「哪个云服务更好」，而是「数据是否应该经过第三方服务器」。以前我们默认选云同步；如今通过 Syncthing 的 P2P 方案，文件直接在设备间传输，因为隐私和控制权才是开发者数据的正确归宿。

Syncthing 给出了答案：P2P + 开源 + 免费。两台机器直接同步，无需中央服务器，在无法访问互联网时自动切换为局域网同步。本指南涵盖 Mac + Windows 11 的配置流程与实用同步模式。

TL;DR

在两台机器上安装 Syncthing — Mac 使用 brew，Windows 使用 winget
交换各机器的 Device ID — 一次性注册
共享文件夹 — 一侧发起，另一侧接受
用 .stignore 排除依赖包/密钥 — 绝不同步 node_modules 或 .env

前置条件

Mac：macOS 12+（已安装 Homebrew）— Mac 初始配置
Windows：Windows 10/11（winget 可用）— Windows 初始配置
两台机器在同一局域网时同步最快（也支持通过互联网跨网络同步）
两台机器均需开机才能同步（休眠中的机器唤醒后会继续同步）

1. 为什么选 Syncthing — 与替代方案对比

工具	模式	容量上限	数据存放位置	费用	评价
Syncthing（推荐）	P2P，开源	仅受磁盘限制	本地机器	免费	M0–M2 推荐
iCloud Drive	云	5GB 免费 / 付费 200GB+	Apple	按月收费	Mac 优先，Win 客户端功能有限
OneDrive	云	5GB 免费 / 付费 100GB+	MS	按月收费	Win 友好，Mac 可用
Dropbox	云	2GB 免费 / 付费 2TB	Dropbox	按月收费	免费容量极小
Resilio Sync	P2P，闭源	无限制	本地机器	按月收费（Pro）	功能更多但需付费
Git	版本控制	仓库限制	GitHub 等	免费	不适合大型二进制文件/中间产物
rsync（手动）	同步	无限制	本地机器	免费	无自动化

Syncthing 的优点：无容量限制，数据仅在本地磁盘（隐私保护），免费，两个系统的客户端功能对等。

缺点：两台机器须同时在线（不适合备份用途），冲突需手动解决，GUI 界面较粗糙（基于浏览器）。

2. 安装

Mac

brew install --cask syncthing
# 或作为后台服务运行（登录时自动启动）
brew services start syncthing

GUI：http://127.0.0.1:8384 — 浏览器中的管理界面。

Windows 11

# winget（无需管理员权限）
winget install -e --id Syncthing.Syncthing

或使用 Syncthing Windows Setup 安装程序（含托盘图标 + 自动启动）。

安装后，右键点击托盘图标 → 「Open」打开 GUI（http://127.0.0.1:8384）。

Mac 自动打开 GUI；Windows 通过托盘打开。两者使用相同的 Web UI。

3. 首次配对 — 连接两台机器

3.1 获取 Device ID

在每台机器的 Syncthing UI 中：

右上角 Actions → Show ID
复制长字符串（XXXXXXX-XXXXXXX-...）

3.2 在 Mac 上添加 Windows

Mac Syncthing UI → Add Remote Device（右下角）
Device ID：粘贴 Windows 的 ID
Device Name：Win11-Desktop（自定义）
保存

3.3 在 Windows 上接受连接

几乎立刻，Windows 会弹出通知：Device <Mac ID> 想要连接 → Add Device → 命名为 MacBook-Pro → 保存。

两端 UI 现在均显示对方为 Connected（绿色）。

同一局域网约 5 秒完成连接；跨网络通过互联网需 1–2 分钟（经 Discovery + Relay）。

4. 首个共享文件夹

4.1 Mac → Windows 方向

Mac UI：

Add Folder
Folder Label：notes（自定义）
Folder ID：notes-mac-win（唯一值，两端必须一致）
Folder Path：/Users/{me}/Documents/notes
Sharing 标签 → 勾选 Win11-Desktop
保存

4.2 在 Windows 上接受并选择路径

Windows UI 弹出通知：「MacBook-Pro 想共享文件夹 'notes-mac-win'」 → Add

Folder Path：C:\Users\{me}\Documents\notes（与 Mac 结构对应便于管理）
保存

4.3 结果

等待两端文件夹均显示 Up to Date（绿色）。首次运行会单向复制所有文件，耗时与总大小成正比。之后，变化会快速同步（通常在 5 秒内）。

5. `.stignore` — 不同步的内容

最常见的错误是同步了 node_modules / .git / .env。依赖包应在各机器上重新构建；Git 文件夹在同步过程中可能损坏；.env 是机密文件。全部排除。

5.1 下载模板

开发文件夹用：

.stignore

# Mac/Linux
curl -fsSL https://devalice.jaceclub.com/assets/multi-os/file-sync/stignore-dev.txt -o /path/to/folder/.stignore
shasum -a 256 /path/to/folder/.stignore
# 预期值：f003177e7026492848825e42c4b4845d1c68f787b923ce44854cb47e9c859827

# Windows PowerShell
Invoke-WebRequest -Uri https://devalice.jaceclub.com/assets/multi-os/file-sync/stignore-dev.txt -OutFile C:\path\to\folder\.stignore
Get-FileHash C:\path\to\folder\.stignore -Algorithm SHA256

5.2 应用

将 .stignore 放在同步文件夹根目录
Syncthing UI → 对应文件夹 → Edit → Ignore Patterns 标签 → 启用 Use .stignore
触发 Rescan → 忽略的文件立即被排除

5.3 关键忽略规则

规则	原因
`node_modules`、`.venv`、`target`	依赖包 — 各机器分别构建
`.git`	损坏风险 + 使用 Git 管理版本
`dist`、`build`、`.next`	构建产物 — 可复现
`.env`、`.env.local`、`.pem`、`id_`	密钥 — 绝不同步
`.DS_Store`、`Thumbs.db`	系统元数据
`*.log`、`tmp`	日志/临时文件

6. 实用模式

6.1 Dotfiles 同步

不要同步整个 home 目录（存在密钥泄露风险）。将 dotfiles 整理到 ~/dotfiles/ 文件夹并创建符号链接。

~/dotfiles/
├── .gitconfig
├── .zshrc
├── .vimrc
└── .tmux.conf

# Mac/Linux
ln -s ~/dotfiles/.zshrc ~/.zshrc
ln -s ~/dotfiles/.gitconfig ~/.gitconfig

# Windows — PowerShell profile 路径不同
ln -s C:\Users\me\dotfiles\Microsoft.PowerShell_profile.ps1 $PROFILE

通过 Syncthing 共享 ~/dotfiles/。通过子文件夹处理系统差异（dotfiles/common、dotfiles/mac、dotfiles/windows）。

6.2 笔记同步

共享 Obsidian / Logseq 的 vault 文件夹。冲突比 iCloud / OneDrive 少（Syncthing 按文件处理冲突，而非按行 — 同时编辑时仍需小心）。

6.3 项目源码同步（注意事项）

原则：尽可能使用 Git。Syncthing 仅用于需要本地同步的附属文件（草稿、每个环境的配置、实验笔记）。

如果必须同步源码文件夹，务必在 .stignore 中排除 .git。同步过程中修改 Git 内部文件有损坏 reflog/index 的风险。

6.4 仅发送 / 仅接收

文件夹类型（文件夹 → Edit → Folder Type）：

Send & Receive（默认）— 双向同步
Send Only — 此机器为主控。忽略并拒绝另一侧的修改
Receive Only — 只接收。本地修改不会同步到另一侧

将备份接收机器设置为 Receive Only 可防止意外的双向覆盖。但真正的备份仍需专用工具（restic、Time Machine）。

7. 冲突处理

两端同时编辑同一文件时，Syncthing 会自动创建冲突文件：

foo.md（最后使用的版本）
foo.sync-conflict-20260512-153012-DEVICE.md（另一侧的版本）

处理流程

打开两个文件进行对比（VS Code「Compare with Active」或 diff foo.md foo.sync-conflict-*.md）
合并到 foo.md
删除 sync-conflict 文件

频繁冲突意味着在同一文件夹中同时编辑。对于笔记，可分机器建立子文件夹（notes/mac/、notes/win/）来避免冲突。

8. 安全

设备认证

Device ID 是公钥哈希（TLS），无法伪造
新设备连接请求需在两端明确批准

数据传输

所有流量使用 TLS 1.2+
局域网内直连；通过互联网时经公共 Relay — Relay 只转发密文

.stignore 中的密钥规则

务必忽略 .env、*.pem、id_*、.aws/credentials
本指南提供的 stignore-dev.txt 已涵盖这些规则

验证

在两台机器上依次执行：

在 Mac 上创建 notes/test.md → 10 秒内出现在 Windows
在 Windows 上编辑 notes/test.md → 10 秒内反映到 Mac
在 Mac 上删除 notes/test.md → 10 秒内从 Windows 消失
两端同时编辑 → 出现 sync-conflict-... 文件（按第 7 节处理）
一端创建的 node_modules / .env 等不会同步到另一端

故障排查

两台机器互相找不到

是否在同一局域网？（跨网络时，等待最多 5 分钟）
防火墙是否允许 Syncthing 端口 22000
Mac：系统设置 → 网络 → 防火墙关闭，或允许 Syncthing
Windows：PowerShell Get-NetFirewallApplicationFilter | ? { $_.Program -match 'syncthing' }

同步速度慢

超大文件夹（数万个文件）— 首次扫描耗时较长。调高 Folder → Edit → Rescan Interval
通过 Relay 经互联网同步 → 速度慢。优先使用同一局域网
磁盘 I/O 瓶颈 — 推荐使用 SSD

长期显示「Out of sync」

Folder → Override Changes（Send & Receive 模式）— 强制以此机器为主控
或 Revert Local Changes（Receive 模式）
两者均可能导致数据丢失；操作前请先备份

.stignore 未生效

确认 Folder → Edit → Ignore Patterns 中已勾选 Use .stignore
.stignore 必须位于文件夹根目录（不是子文件夹）
触发 Rescan（Folder → ⋮ → Rescan）

Windows 托盘图标不见了

winget install 可能未自动启动
Syncthing Windows Setup 安装程序可添加托盘图标 + 自动启动
或通过任务计划程序在登录时执行 syncthing.exe --no-console --no-browser

密钥文件意外同步

立即在两台机器上删除该文件
Syncthing 可移至回收站（Folder → File Versioning）
立即轮换密钥本身（API 密钥等）— 假定另一台机器已接触到该文件
将对应规则添加到 .stignore 防止再次发生

参考资料

Mac 初始配置 / Windows 初始配置 — Homebrew/winget 前置条件
Mac ↔ Windows 输入共享 — 相关指南
Syncthing 官方文档 — 文件夹类型、版本管理、API
.stignore 语法

更新日志

2026-05-12：初稿。替代方案对比 + Mac+Win 配置 + 五种实用模式 + 冲突处理 + 六个故障排查案例 + .stignore 模板资源。

文件同步 — 用 Syncthing 实现 Mac ↔ Windows P2P 文件夹同步