GeoTag Pro

現代化 Electron 桌面照片 GPS 標註工具

GeoTag Pro 是一個專業的桌面應用程式，讓您輕鬆為照片批量添加 GPS 座標資訊到 EXIF 元資料中。

🖼️ Screenshots

✨ 主要功能

• 批量匯入照片: 支援 JPG、PNG、TIFF 格式
• 互動式地圖: 整合 OpenStreetMap，直觀選擇 GPS 座標
• 批量 GPS 寫入: 一次為多張照片添加相同的 GPS 資訊
• 即時進度顯示: 清楚顯示處理進度與成功/失敗狀態
• EXIF 預覽: 查看照片的完整 EXIF 資訊
• 深色模式: 支援深色/淺色主題切換
• 地圖搜尋: 快速定位到特定地點
• 手動座標輸入: 直接輸入精確的 GPS 座標
• 安全性: 採用 Electron contextIsolation 與 CSP 防護

📦 安裝

系統需求

• Windows 11 (或 Windows 10 1903+)
• Node.js 18+
• 2GB RAM 以上
• 500MB 可用硬碟空間

執行EXE安裝檔

1. 下載最新版本的執行檔（.exe）從 Releases 中下載。
2. 雙擊執行檔，即可使用。

從原始碼安裝

# 克隆專案
git clone https://github.com/your-username/geotag-pro.git
cd geotag-pro

# 安裝依賴
npm install

# 啟動開發模式
npm run dev

# 建構應用程式
npm run build

# 打包安裝檔
npm run dist

🚀 快速開始

1. 匯入照片: 點擊「選擇照片」按鈕或拖放照片到應用程式
2. 選擇照片: 在左側邊欄勾選要添加 GPS 的照片
3. 定位座標: 在地圖上拖曳到目標位置，或使用搜尋列尋找地點
4. 寫入 GPS: 點擊「寫入 GPS 至所選照片」按鈕
5. 確認結果: 查看進度動畫，成功的照片會顯示綠色勾選標記

🧑‍💻 測試與開發

執行測試（如有）

npm run test

程式碼格式檢查

npm run lint

若尚未有測試，建議未來補上單元測試與 CI。

🏗️ 技術架構

• 前端框架: React 18 + TypeScript
• 桌面框架: Electron 30
• 建置工具: Vite 5
• 狀態管理: Zustand
• 地圖: Leaflet.js + React-Leaflet
• 樣式: Tailwind CSS 3
• EXIF 處理: exifreader + piexifjs
• 設定存儲: electron-store

📁 專案結構

GeoTag/
├── src/
│   ├── main/             # Electron 主程序
│   │   ├── index.ts      # 應用程式入口
│   │   ├── photoImport.ts # 照片匯入邏輯
│   │   ├── gpsWriter.ts  # GPS 寫入邏輯
│   │   ├── exifReader.ts # EXIF 讀取邏輯
│   │   └── settings.ts   # 設定管理
│   ├── renderer/         # React 渲染程序
│   │   ├── components/   # UI 元件
│   │   ├── store/       # Zustand 狀態管理
│   │   ├── App.tsx      # 主應用程式
│   │   └── main.tsx     # React 入口
│   ├── preload/         # Preload 腳本
│   │   └── index.ts     # IPC API 暴露
│   └── shared/          # 共用型別定義
│       └── types.ts
├── specs/               # 功能規格文件
├── docs/                # 文件資料
└── package.json

🙋 FAQ & 常見問題

Q: 啟動時出現 node-gyp 或 native module 編譯錯誤？ A: 請確認已安裝 Visual Studio Build Tools 並重啟終端機。

Q: 地圖無法載入？ A: 請檢查網路連線，或參考 docs/FAQ.md 取得更多協助。

🔒 安全性

GeoTag Pro 遵循 Electron 安全最佳實踐：

• ✅ Context Isolation 啟用
• ✅ Node Integration 禁用
• ✅ 僅透過 Preload 腳本暴露必要 API
• ✅ Content Security Policy (CSP) 設定
• ✅ 嚴格的 TypeScript 型別檢查

🤝 貢獻

歡迎提交 Pull Request 或開 Issue 回報問題！

貢獻流程

1. Fork 本專案
2. 建立分支（如 feat/your-feature）
3. 提交 PR，請詳述修改內容與測試方式
4. 通過審查後合併

請遵守 CODE_OF_CONDUCT.md（如有）

📄 授權

本專案採用 MIT License，詳見 LICENSE 檔案。

🙏 致謝

• OpenStreetMap - 地圖數據
• Leaflet - 地圖庫
• Electron - 桌面應用框架
• React - UI 框架

---

開發者: GeoTag Pro Team
最後更新: 2026-02-11

📝 Changelog

請參見 CHANGELOG.md 以獲取發行紀錄。