# 使用 Dropbox 的雲端同步

把你的專案庫專案與設定備份到你自己的 Dropbox，並在你的其他電腦上開啟。包含同步哪些內容、如何處理衝突與刪除，以及每則訊息的意思。

雲端同步會在你自己的 Dropbox 中保存專案庫專案與設定的副本。在另一台電腦上連接同一個 Dropbox，並在那裡下載你的專案，兩台電腦就會讓專案保持同步。

開啟 **設定 → 資料儲存 → 雲端同步** 即可設定。

## 開始之前

- 你需要一個 Dropbox 帳號。免費的 Dropbox Basic 帳號有 2 GB。
- 雲端同步可在 macOS、Windows 與 Linux 上使用。
- Oleafly 只在開啟時才會同步，包括視窗縮到最小或隱藏的時候。Oleafly 關閉時不會同步任何內容。
- Oleafly 直接與 Dropbox 通訊，中間沒有 Oleafly 伺服器。

## 連接 Dropbox

1. 開啟 **設定 → 資料儲存 → 雲端同步**，選擇 **連接 Dropbox**。
2. 瀏覽器會開啟 Dropbox 的登入與核准頁面。在那裡登入並核准 Oleafly。
3. Oleafly 完成連接後，瀏覽器會顯示「你已連接」。如果你核准後出了問題，瀏覽器會顯示登入未完成，Oleafly 則會說明發生了什麼事。

你是在 Dropbox 自己的頁面登入，所以 Oleafly 永遠看不到你的 Dropbox 密碼。

### 如果瀏覽器無法交還給 Oleafly

你核准之後，Dropbox 會把瀏覽器導向你電腦上的本機位址 (127.0.0.1)，Oleafly 會從那裡接手登入。如果這行不通，請選擇 **登入有問題？貼上代碼**。Dropbox 會顯示一組代碼。複製它並貼到 Oleafly 中。

### Oleafly 能存取的範圍

- Oleafly 只能開啟你 Dropbox 中屬於自己的應用程式資料夾 `Apps/Oleafly`，看不到你 Dropbox 中的其他任何檔案。
- 它只會向 Dropbox 要求四項權限，不會多要。`account_info.read` 用來顯示你的電子郵件地址和已用空間。`files.metadata.read`、`files.content.read` 與 `files.content.write` 讓它能列出、讀取並寫入自己資料夾中的檔案。
- 登入使用帶有 PKCE 的 OAuth。
- 在 macOS 與 Windows 上，登入權杖存放在作業系統的鑰匙圈中。在 Linux 上，或鑰匙圈無法使用時，則存放在 Oleafly 資料夾中的加密檔案。
- 權杖絕不會同步。每台電腦都各自連接。

### 雲端同步卡片

連接之後，卡片會顯示：

- Dropbox 帳號的電子郵件地址。
- 一個圓環，顯示你的 Dropbox 已使用多少。隨著 Dropbox 逐漸填滿，它會從綠色轉為黃色、橘色和紅色，達到 80% 起為紅色。
- **在這台電腦上同步**，也就是在這裡開啟或關閉同步的開關。
- **自動同步**，讓 Oleafly 自行同步的開關。
- 這台電腦的名稱。點選它可以重新命名這台電腦。
- **專案** 清單。
- **進階**，其中有 **中斷連接**。

## 同步哪些內容

### 專案

專案庫中的每個專案都會連同其檔案一起同步，包括你的主文件編譯所在的資料夾。Oleafly 會悄悄略過每個專案中的下列項目：

- 建置輸出，例如 `.aux` 與 `.log` 檔案，以及編譯出的主 PDF。你用 Git 追蹤的建置檔案（例如結果記錄）仍會備份到你的 Dropbox。
- Python 的 `__pycache__` 資料夾
- `.git` 資料夾
- Oleafly 自己的工作資料夾
- 編輯器產生的暫存檔
- 系統檔案，例如 `.DS_Store`

另外有少數項目也不會同步，專案那一列會把它們列為已略過並附上原因：符號連結、`node_modules` 與 `.venv` 資料夾、大於 16 GB 的檔案，以及[名稱無法在每台電腦上使用](#renames-and-file-names)的檔案。

你從電腦上其他位置的資料夾開啟的專案（[在原位置開啟的資料夾](/docs/library/#folders-opened-in-place)）不會同步。專案清單會告訴你有幾個。

Git 記錄與[檢查點](/docs/checkpoints/)不會同步。

### 專案詳細資料

每個專案的 `project.json` 也會同步，所以它的名稱、主文件、引擎、封面顏色與其他詳細資料都會跟著走。有少數詳細資料屬於單一電腦，會留在該電腦上：

- 匯出路徑
- 專案是否隱藏
- TeX 套件規格
- 檢查點擷取政策
- 它是從哪個專案複製而來

### 筆記

每則個人[筆記](/docs/notes/)的同步方式與專案庫專案相同，專案內的筆記則會隨該專案的檔案一起同步。如果個人筆記在兩台電腦上都有變更，另一台電腦的版本會以衝突副本的形式存放在該筆記的資料夾中，例如 `note (Laptop 2026-10-14).md`，你可以用筆記選單中的 **比較衝突副本** 保留其中一個版本。專案內的筆記，其衝突副本會放在專案的 `notes` 資料夾中該筆記旁邊，和其他專案檔案一樣。

### 設定

你的應用程式設定會同步，包括 AI 指示、AI 角色與你的自訂字典。有些設定會留在每台電腦上，例如 **自動同步** 是否開啟、LaTeX 的 **預設編譯引擎**、終端機的 **Shell** 與 **Shell 路徑**、整合中的 **Computer Use**、實驗功能中的 **研究任務** 開關，以及研究中的 **預設允許任務指令存取網路**。這樣一來，代理程式就不會只因為你在別處開啟了桌面應用程式，就在這台電腦上取得它們；沒有安裝 TeX 的電腦，在另一台電腦使用 latexmk 時也會繼續使用 Tectonic。

AI 對話、密碼、API 金鑰與其他機密資料永遠不會同步。

## 你的 Dropbox 中有什麼

所有內容都放在 `Apps/Oleafly` 資料夾中：

```text
Apps/Oleafly/
├── projects/
│   └── <project id>/
│       ├── files/          the project's files, under their own names
│       └── version.json    which version of each file belongs to the project
└── settings/
    └── settings.json       your synced settings
```

專案檔案保有自己的名稱，所以你可以從 Dropbox 開啟它們。不支援手動編輯或移動 `Apps/Oleafly` 中的檔案。Oleafly 會把該資料夾中的所有內容視為不受信任，並加以檢查。

## 一輪同步如何運作

每一輪都會經過相同的步驟：

1. Oleafly 向 Dropbox 詢問自上一輪以來有哪些專案變更。如果沒有任何變更，只需要一次請求。
2. 它會掃描這台電腦上每個專案的檔案。它能快速辨識未變更的檔案，不必重新讀取。
3. 對每個檔案，它會比較三個版本：這台電腦上的版本、Dropbox 中的版本，以及雙方上次一致的版本。藉此得知是哪一邊有變更。
4. 它會先把你其他電腦的變更下載到暫存位置，並對照為該檔案記錄的指紋（雜湊值）加以檢查。通過後，檔案才會進入專案。如果你在掃描之後又在這台電腦上改了該檔案，Oleafly 會先不動它，等到下一輪。
5. 它會上傳這台電腦的變更，然後拿 Dropbox 自己的校驗和與送出的內容比對。
6. 它會儲存專案的版本記錄，並確認這段期間沒有其他電腦儲存過。如果有，這一輪會用較新的記錄重新執行，所以任何一台電腦的工作都不會遺失。
7. 最後，它會把你在這台電腦上刪除的檔案從 Dropbox 移除。

## Oleafly 何時同步

**自動同步** 除非你關閉，否則會一直開啟。開啟時，Oleafly 會在你儲存檔案後幾秒鐘同步，也會在另一台電腦變更你的 Dropbox 後不久同步。在這些時機之間，它每 5 分鐘檢查一次，Oleafly 視窗隱藏時則每 15 分鐘檢查一次。第一輪大約在 Oleafly 啟動後 20 秒執行，設定的變更會在你變更後約 3 秒同步。關閉 **自動同步** 後，Oleafly 會在你選擇 **立即同步** 時同步，並在你連接、重新開啟 **在這台電腦上同步**，或重新開啟某個專案的開關時各同步一次。

如果某一輪失敗（例如因為你離線），Oleafly 會在 30 秒後重試，之後每次失敗都等得更久，最長 5 分鐘，視窗隱藏時則最長 15 分鐘。一旦有一輪成功，就會回到正常的排程。電腦重新上線時，它也會同步。

**立即同步** 會立刻執行一輪，並顯示一則結果訊息。自動執行的輪次從不跳出視窗。它們的狀態會顯示在專案區段中：「上次同步」加上時間、「正在同步你的專案」，或一行說明問題的文字。

當有事情需要你處理時，例如 Dropbox 已滿、專案已暫停、出現衝突副本或需要做設定選擇，設定按鈕上會出現一個小小的琥珀色圓點。接著設定會直接開在雲端同步，讓你先看到哪裡有問題。

## 衝突

如果同一個檔案在兩次同步之間於兩台電腦上都有變更，Oleafly 會保留兩個版本。這台電腦的版本維持原本的名稱。另一台電腦的版本會儲存在它旁邊，並以寫入它的電腦名稱與日期命名，例如 `ch1 (Laptop 2026-10-14).tex`。同一天的第二次衝突會在名稱後加上編號。專案那一列會列出衝突副本，直到你選擇 **關閉**。

開啟兩個檔案，保留你要的內容，並刪除不需要的副本。

`project.json` 絕不會產生衝突副本，它的欄位會改為合併。每台電腦的變更都會保留；如果兩台電腦變更了同一個欄位，則以這台電腦的值為準。

### 未儲存的編輯是安全的

同步絕不會覆寫在編輯器中開啟、且有未儲存變更的檔案。來自你其他電腦的變更會等待。你儲存之後，下一輪會把你的編輯當成一般的編輯處理，所以如果兩邊都改了該檔案，你會得到一份衝突副本。

你尚未更動的開啟檔案，會在另一台電腦的變更到達時立即在編輯器中更新。如果變更在你編輯期間到達，編輯器會告知該檔案已在磁碟上變更，由你選擇 **重新載入** 或 **保留我的版本**。新檔案與衝突副本會出現在檔案樹中，在另一台電腦上刪除的檔案則會在這裡關閉。

### 重新命名與檔案名稱

只更改檔案名稱的大小寫，算作重新命名，而不是刪除。

Oleafly 會略過下列檔案，並把它們列在專案那一列之下：

- 名稱無法在每台電腦上使用的檔案，例如名稱含有 `:`，或像 `CON.tex` 這樣的名稱
- 名稱與同一資料夾中的另一個名稱只有大小寫不同的檔案。已經在同步的那個檔案會繼續同步。

清單也會顯示 Oleafly 在這裡無法讀取，或無法下載或上傳的檔案。下載失敗的檔案會在一小時後重試，如果檔案有變更則會更早。

## 刪除檔案

當你在一台電腦上刪除檔案，它在你的其他電腦上也會被刪除。在那裡，檔案會移到系統的垃圾桶或資源回收筒；如果系統沒有，則移到 Oleafly 自己的垃圾桶資料夾。你可以從那裡找回它。

Dropbox 中缺少某筆記錄，絕不會導致電腦上的檔案被刪除。如果有人在 Dropbox 中手動刪除專案的資料夾，Oleafly 會重新上傳該專案。如果 Dropbox 中某個專案的記錄缺少 `project.json`，Oleafly 會重新上傳該檔案，而不是刪除它。

### 防止大量刪除檔案的保護

如果某個專案超過一半的檔案在一台電腦上被一次刪除，而且數量超過 20 個，Oleafly 不會把這次刪除傳遞出去。專案中的每個檔案都被刪除時，也會這樣處理。移動或重新命名資料夾不算在內，因為檔案仍然存在。專案會顯示「為保護你的檔案而暫停」，並提供兩個選項：

- **放回去** 會從 Dropbox 還原這些檔案。
- **也從 Dropbox 刪除** 會在你確認後，同樣從 Dropbox 刪除它們。你的其他電腦隨後也會失去這些檔案。

同樣的檢查也適用於相反的情況。如果專案在 Dropbox 中的記錄突然缺少許多檔案，例如記錄是從較舊的版本還原的，Oleafly 不會在這台電腦上刪除它們。專案會顯示「為保護你的檔案而暫停」，並提供兩個選項：

- **放回 Dropbox** 會把這台電腦上的檔案重新上傳。
- **也在這裡刪除** 會在你確認後，把它們移到這台電腦的資源回收筒。

## 專案清單

專案庫中的每個專案都有一列，顯示它的大小與上次同步的時間。

- 它的開關用來在這台電腦上同步該專案，或在這裡暫停同步。
- 只存在於 Dropbox 的專案有一個下載按鈕。**全部下載** 會下載所有這類專案，但在這台電腦資源回收筒中的專案除外。下載的專案會出現在你的專案庫中。
- 如果專案在這台電腦的資源回收筒中，下載它會從資源回收筒還原，而不是建立第二份副本。下一次同步會帶入在其他地方所做的變更。
- 從 Dropbox 下載的專案會以受限模式開啟，直到你在那台電腦上信任它。你會看到與[在原位置開啟的資料夾](/docs/library/#folders-opened-in-place)相同的信任提示。

### 從 Dropbox 移除專案

若要釋出空間，請在專案那一列的 **…** 選單中選擇 **從 Dropbox 移除**。這會刪除專案在 Dropbox 中的副本。專案會留在這台電腦上，並在這裡停止同步。你的其他電腦會保留它們的副本，並顯示「在 ○○ 上已從 Dropbox 移除」，其中 ○○ 是這台電腦的名稱。

重新開啟專案的開關即可再次上傳。

只存在於 Dropbox 的專案，選單中同樣有 **從 Dropbox 移除**。這會把它們從你的 Dropbox 刪除，所以之後你就無法在這台電腦上下載它們。已經有這些專案的電腦會保留自己的副本。

如果 Dropbox 無法立即刪除該資料夾，專案仍會顯示為已移除，Oleafly 會在之後的同步中完成刪除。

## 儲存空間與已滿的 Dropbox

雲端同步卡片上的圓環顯示你的 Dropbox 已使用多少，達到 80% 起會變紅。免費的 Dropbox Basic 帳號有 2 GB。

當你的 Dropbox 已滿，上傳會停止，但下載仍可運作。橫幅會告知你，每個無法上傳的專案也會顯示。已滿期間，Oleafly 會在上傳之前先檢查剩餘空間，所以絕不會送出放不下的檔案。若要騰出空間，請做下列其中一件事：

- 關閉大型專案的同步。
- 從 Dropbox 移除專案。
- 釋出 Dropbox 中的空間。

一有空間，同步就會自動繼續。

## 離線與中斷的同步

離線時，你的編輯會留在電腦上，不會遺失任何內容。連線恢復後，同步會繼續進行。

如果某一輪在途中停止（例如網路中斷或你關閉了 Oleafly），下一輪會完成剩下的工作。耗時較長的第一次備份每 200 個檔案或 256 MB 就會儲存一次進度，所以不會從頭開始。關閉 **在這台電腦上同步** 會停止正在執行的一輪。

當 Git 指令正在變更專案的檔案時（例如在終端機中執行 checkout 或 pull），這一輪會等待，並在下一次再試。在 Windows 上，被其他程式開啟的檔案會在幾分鐘後再試。

當 Dropbox 要求 Oleafly 放慢速度，或發生暫時性錯誤時，Oleafly 會自行重試。

如果這台電腦的磁碟空間不足，下載會等到你釋出一些空間才繼續。上傳則照常進行。

## 設定同步

一台電腦第一次連接時，Oleafly 會比較它的設定與你 Dropbox 中的設定。如果兩者不同，它會詢問一次：「Oleafly 應該使用哪一份設定？」請選擇 **使用 Dropbox 的設定** 或 **保留這台電腦的設定**。如果你關閉對話框，它不會自己再跳出來。同樣的兩個選項會留在雲端同步卡片上等你，在你選擇之前不會覆寫任何內容。

在那之後，設定會自動合併：

- 在不同電腦上對不同設定所做的變更都會保留。
- 如果同一項設定在兩邊都有變更，以這台電腦的值為準。
- 清單（例如字典中的字詞）會合併。AI 角色會逐一合併，所以在兩台電腦上都編輯過的角色仍然只是一個角色。

若要自行從 Dropbox 載入設定，請開啟 **設定 → 一般 → 匯入** 並選擇 **從雲端匯入**。你會看到與匯入設定檔時相同的檢視步驟。

## 電腦與帳號

### 為這台電腦命名

每台電腦都有一個名稱。起初是電腦的主機名稱。點選雲端同步卡片上的名稱即可更改。你的其他電腦會在衝突副本與「已從 Dropbox 移除」的備註上顯示這個名稱。

### 中斷連接

開啟 **進階**，選擇 **中斷連接** 並確認。這台電腦會停止同步，Oleafly 對你 Dropbox 的存取權也會被移除。你的專案會留在這台電腦與你的 Dropbox 中。如果此時 Oleafly 無法連上 Dropbox，它仍會在這裡中斷連接並告訴你，你可以自行在 Dropbox 的已連結應用程式中移除 Oleafly。

### 切換到另一個 Dropbox 帳號

連接不同的 Dropbox 帳號會重新開始。不會與舊帳號進行任何比對，也不會因此刪除任何內容。

### 存取權終止時

如果 Oleafly 的存取權終止（例如你在 Dropbox 的已連結應用程式中移除了 Oleafly），卡片會顯示「Dropbox 存取權已終止。請重新連接以繼續同步。」請選擇 **重新連接**。

### 另一台電腦上較新的 Oleafly

如果另一台電腦執行較新版本的 Oleafly，並以較新的格式儲存了專案，較舊的版本會停止同步該專案，並要求你[更新 Oleafly](/docs/updates/)。

## 安全檢查

- 來自 Dropbox 的每個檔案，在取代任何內容之前，都會先對照其記錄的指紋檢查。
- 來自 Dropbox 的任何內容都不會寫入 `.git`、專案資料夾之外，或透過符號連結寫入。
- 來自 Dropbox、但這個版本的 Oleafly 無法開啟的 `project.json`，絕不會取代這台電腦上的那一份。
- 你曾信任其在編譯時執行 shell 指令的專案，在檔案從 Dropbox 抵達後，下次編譯前會再次詢問，就和 Git pull 之後一樣。
- Oleafly 會把 `Apps/Oleafly` 中的所有內容視為不受信任，並加以檢查。
- Oleafly 不會為你在 Dropbox 中的檔案加上端對端加密。它們就像其他任何檔案一樣存放在你的 Dropbox 中。

## 疑難排解

| 訊息或症狀 | 處理方式 |
| --- | --- |
| 瀏覽器沒有交還給 Oleafly | 選擇 **登入有問題？貼上代碼**，並貼上 Dropbox 顯示的代碼。 |
| 「Dropbox 存取權已終止。請重新連接以繼續同步。」 | 選擇 **重新連接**，並在瀏覽器中核准 Oleafly。 |
| 「Oleafly 應該使用哪一份設定？」 | 選擇 **使用 Dropbox 的設定** 或 **保留這台電腦的設定**。關閉對話框可稍後在雲端同步卡片上決定。不會覆寫任何內容。 |
| 「為保護你的檔案而暫停」 | 很多檔案在這裡或 Dropbox 中被一次刪除。要保留它們，請選擇 **放回去** 或 **放回 Dropbox**；如果你本來就打算刪除，則選擇 **也從 Dropbox 刪除** 或 **也在這裡刪除**。 |
| 出現像 `ch1 (Laptop 2026-10-14).tex` 這樣的檔案 | 這是以其名稱所示電腦產生的衝突副本。比較兩個檔案，保留你要的，並刪除另一個。 |
| 專案那一列顯示有檔案被略過 | 開啟清單查看每個檔案及原因。請為名稱無法在每台電腦上使用，或與其他名稱衝突的檔案重新命名。 |
| 設定按鈕上有琥珀色圓點 | 雲端同步需要你處理。開啟設定並閱讀雲端同步卡片。 |
| 「Oleafly 無法讀取你 Dropbox 中的副本，所以這個專案沒有在同步。」 | 選擇 **以這台電腦的副本取代**。只存在於 Dropbox 副本中的內容會遺失，所以請先檢查你的其他電腦。 |
| 「Oleafly 無法讀取你 Dropbox 中的設定。」 | 選擇 **使用這台電腦的設定** 來取代它們。 |
| 「這台電腦的磁碟空間快用完了。」 | 釋出磁碟空間。同步會自動繼續。 |
| 「這個專案有超過 100,000 個檔案。多到無法同步。」 | 把專案不需要的檔案移出它的資料夾。 |
| 「在（電腦名稱）上已從 Dropbox 移除」 | 那台電腦把專案從 Dropbox 移除了。你這裡的副本是安全的。開啟專案的開關即可再次上傳。 |
| 「你的 Dropbox 已滿。」 | 關閉大型專案的同步、從 Dropbox 移除專案，或釋出 Dropbox 中的空間。下載仍可運作，一有空間同步就會繼續。 |
| 「你的 Dropbox 已達到本月的上傳上限。」 | Dropbox 會限制部分帳號每月的上傳量。你的編輯會留在這台電腦上，等 Dropbox 再次允許上傳後就會上傳。 |
| 「無法連上 Dropbox。Oleafly 會再試一次。」 | 檢查你的連線。你的編輯會留在這台電腦上，等你重新上線後 Oleafly 就會同步。 |
| 「這個專案是由較新版本的 Oleafly 同步的。請更新 Oleafly 以繼續同步它。」 | 在這台電腦上[更新 Oleafly](/docs/updates/)。 |
| 下載的專案以受限模式開啟 | 確認其中內容之後，再在這台電腦上信任它。 |
| 什麼都沒有同步 | 確認 **在這台電腦上同步** 已開啟，且專案的開關也已開啟。Oleafly 只在開啟時才會同步。如果 **自動同步** 已關閉，請選擇 **立即同步**。 |

想改用 Git 搬移專案？請參閱 [GitHub 同步](/docs/github-sync/)。想了解 Oleafly 在你電腦上保存的所有內容，請參閱[你的檔案與資料](/docs/where-your-data-lives/)。
