前言：為什麼我想整理這篇教學
自從 Karpathy 再次談到大型語言模型需要更穩定的外部知識整理方式之後，Obsidian 這類以本地筆記、資料連結與知識管理為核心的工具，也再次受到不少人的關注。這波討論讓很多人重新意識到，筆記軟體不只是拿來做摘錄而已，而是可能成為個人長期保存資料、整理脈絡、累積知識的重要基礎設施。
也因為如此，我想把自己目前在電腦與 Android 手機之間同步 Obsidian Vault 的方法整理成一篇教學。這篇文章不打算談太多抽象概念，而是聚焦在一個很實際的問題：如果你平常主要在電腦端維護筆記，手機端只是想穩定查看最新內容，那麼該怎麼建立一套足夠簡單、容易維護，出問題時也能快速復原的同步流程。對我來說，使用 Termux 搭配 git、GitHub 與桌面小工具，是目前相對務實的一種做法。
為什麼我改用 Termux 同步 Obsidian
如果你和我一樣，真正整理筆記的地方主要是在電腦，手機上的 Obsidian 比較像是隨身資料庫，用來查資料、翻筆記，而不是長時間編輯內容，那麼 Android 端其實不一定要走外掛路線。相較之下，用 Termux + git + Termux:Widget 來同步 GitHub 上的 Vault，往往更直接，也更穩定。
這套做法的核心觀念很簡單：電腦端負責寫作與整理，完成後推送到 GitHub；手機端則只負責把最新內容拉下來，然後交給 Obsidian 開啟。這樣的分工有一個很大的好處，就是手機端的角色非常清楚。它不是主要工作機，而是內容的瀏覽端。只要這個邏輯建立起來，之後不管是同步、除錯，還是重建環境，都會簡單很多。
開始前要先準備什麼
正式開始之前，先把幾個必要資訊整理好，後面會反覆用到。包括 GitHub repo 的 SSH 位址、預設分支名稱、你的 GitHub 帳號與 Email，以及手機上要開啟的 Vault 資料夾名稱。後續指令中若出現 <你的帳號>、<repo名稱>、<vault名稱>、<你的Email> 這類字樣，都要替換成你自己的實際資料。
如果你的目標很明確，就是讓手機只負責查看最新筆記，那麼這一套流程其實已經夠用，不需要再額外堆疊更多同步工具。
Android 手機端的基本設定流程
第一步是安裝 Termux。這裡建議直接從 F-Droid 安裝，不要使用 Play Store 舊版，因為舊版長期沒有維護，實際操作時很容易碰到套件或權限問題。安裝完成後，可以先在 Termux 裡完成基本初始化：
pkg update && pkg upgrade -y
pkg install git openssh -y
termux-setup-storagetermux-setup-storage 的作用，是讓 Termux 能夠讀寫手機的共享儲存空間。執行後如果系統跳出權限要求，記得要允許，否則後面 clone 出來的 Vault 就無法放到你預期的位置。
接著要建立 SSH 金鑰，讓手機能安全地和 GitHub 溝通：
ssh-keygen -t ed25519 -C "<你的Email>" -f ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub把公鑰內容複製後，加到 GitHub 的 SSH keys 設定頁。完成之後，可以用下面這行測試連線是否正常：
ssh -T [email protected]如果 GitHub 回應你已經成功認證，就可以繼續設定 git 的基本身分：
git config --global user.name "<你的帳號>"
git config --global user.email "<你的Email>"
git config --global pull.rebase false最後，把 GitHub 上的 Vault clone 到手機裡的 Obsidian 資料夾：
mkdir -p ~/storage/shared/obsidian
git clone [email protected]:<你的帳號>/<repo名稱>.git ~/storage/shared/obsidian/<vault名稱>
git config --global --add safe.directory /storage/emulated/0/obsidian/<vault名稱>其中 safe.directory 這一步不要省略。Android 的儲存路徑和 Termux 的執行環境，偶爾會讓 git 判定目錄擁有權異常，先把這個路徑加入安全清單，後面會少掉很多不必要的錯誤。
Clone 完成後，打開 Obsidian，選擇 Open folder as vault，指定到下列路徑即可：
/storage/emulated/0/obsidian/<vault名稱>/到這裡為止，手機端其實就已經能讀取這個 Vault，只是同步還得手動進 Termux 執行 git pull。如果想把這一步也簡化掉，就可以繼續做下一段設定。
把同步變成桌面一鍵完成
真正讓這套流程順手的關鍵，在於把同步這件事變成桌面上的一個按鈕。也就是說，你不必每次都打開終端機輸入指令，而是直接點一下桌面小工具，就把 GitHub 的最新內容拉下來。
這需要另外安裝 Termux:Widget 與 Termux:API，並在 Termux 中補上對應套件：
pkg install termux-api接著建立一個小型同步腳本。以下內容可直接貼入 Termux，記得把 <vault名稱> 換成實際名稱：
cat > ~/.shortcuts/pull-vault.sh <<'EOF'
#!/data/data/com.termux/files/usr/bin/bash
export PATH=/data/data/com.termux/files/usr/bin:$PATH
VAULT="/data/data/com.termux/files/home/storage/shared/obsidian/<vault名稱>"
LOG="/data/data/com.termux/files/home/pull-vault.log"
toast_msg() {
if command -v termux-toast >/dev/null 2>&1; then
termux-toast "$1"
fi
}
{
if [ ! -d "$VAULT" ]; then
toast_msg "同步失敗：找不到 vault"
exit 1
fi
cd "$VAULT" || exit 1
BRANCH="$(git branch --show-current 2>/dev/null)"
RESULT="$(git pull origin "$BRANCH" 2>&1)"
STATUS=$?
echo "$RESULT" >> "$LOG"
if [ $STATUS -eq 0 ]; then
if echo "$RESULT" | grep -q "Already up to date"; then
toast_msg "Obsidian 已是最新版本"
else
toast_msg "Obsidian 同步完成"
fi
else
toast_msg "同步失敗"
exit $STATUS
fi
}
EOF
chmod +x ~/.shortcuts/pull-vault.sh做完之後，把 Termux:Widget 小工具放到 Android 主畫面，指定執行 pull-vault.sh。從此之後，手機端同步就會從「打開終端機、切資料夾、輸入 git pull」這種流程，變成「按一下桌面按鈕」這麼簡單。
這也是我認為這套方法最有價值的地方。你保留了 git 的透明度與可控性，但在日常使用上，體驗又不會像傳統終端機操作那麼笨重。
Windows 端如何快速推送更新
既然手機端已經被簡化成一鍵 pull，那麼電腦端也可以順手做一個一鍵 push。對 Windows 使用者來說，最容易的方法就是建立一個批次檔，把常用的提交流程包起來：
@echo off
cd /d "D:\你的repo資料夾" || (
echo 找不到 repo 路徑
pause
exit /b
)
set msg=%date% %time%
git add .
git commit -m "%msg%"
git push origin main
pause這段腳本的意義不在於炫技，而是把日常同步壓縮成最低成本。你在電腦端更新完 Obsidian 後，只要雙擊一次，就能把所有變更推送到 GitHub。接著手機端再點一下桌面小工具，就完成整套同步流程。
日常使用其實很單純
當整個環境設定完成後，日常操作反而非常單純。你在電腦上正常寫筆記、整理資料、推送到 GitHub；手機上若要查看最新內容，就點一下桌面上的同步小工具，再切回 Obsidian。整體使用感受會很接近「我只是按一個更新按鈕」，而不是「我正在維護一套 Git 系統」。
對於把手機視為閱讀端的人來說，這種模式幾乎已經足夠。你不需要在手機上承擔太多版本控制的複雜性，卻仍然保有 GitHub 帶來的同步與備份優勢。
同步失敗時，怎麼最快復原
只要是 Git 同步，就一定會遇到例外情況。最常見的幾種，包括 SSH 金鑰失效、手機端不小心改到檔案，或者本地 Git 狀態損壞。這時候真正重要的，不是背更多指令，而是知道哪一種處理方式最省時間。
如果只是手機端誤觸修改，導致 git pull 被拒絕，通常可以直接捨棄本地修改：
cd ~/storage/shared/obsidian/<vault名稱>
git checkout .
git pull origin main如果情況更複雜，例如 Git 狀態混亂、物件損壞，或你根本不想再花時間查是哪一步壞掉，那麼最乾淨的方式通常是直接重建本地 Vault：
rm -rf ~/storage/shared/obsidian/<vault名稱>
git clone [email protected]:<你的帳號>/<repo名稱>.git ~/storage/shared/obsidian/<vault名稱>
git config --global --add safe.directory /storage/emulated/0/obsidian/<vault名稱>因為這套架構本來就是以 GitHub 為中心，所以只要遠端 repo 是完整的，手機端重建其實並不可怕。與其在手機上硬解一堆 git 問題，很多時候直接刪掉重 clone，反而是最有效率的選擇。
幾個最常用的指令
最後，把幾個最常用、最值得記住的指令放在一起。平常大多數情況，其實就是靠這幾行在處理：
# 進入 Vault
cd ~/storage/shared/obsidian/<vault名稱>
# 查看狀態
git status
# Pull 最新
git pull origin main
# 捨棄本機修改
git checkout .
# 查看最近提交
git log --oneline -5如果你的使用情境和本文相同，也就是電腦端寫作、手機端唯讀，那麼這套流程的重點其實不是把手機變成完整的 Git 工作站，而是用最少的操作，穩定拿到最新的 Obsidian 筆記。從這個角度來看，Termux 的價值不在於它多強，而在於它剛好能把同步這件事做得足夠透明，也足夠省事。
捲動到此處時自動載入留言…