**GitDiagram：** **新手救星！幾秒後，** **開源專案不再是天書。**

GitDiagram：一鍵將 GitHub 倉庫變成互動式架構圖，新手也能輕鬆理解開源專案！

各位台灣的朋友大家好！常常想參與開源專案，卻被龐大的程式碼量嚇退嗎？或是想快速理解一個 GitHub 專案的架構，卻不知從何下手？今天我要介紹一個超實用的工具 GitDiagram，它能將任何 GitHub 倉庫瞬間轉換成互動式架構圖，讓你像讀地圖一樣輕鬆掌握專案結構，就算你是程式新手也能快速上手！

文章連結（範例）：https://example.com/gitdiagram-taiwan (請替換成你實際發布的網址)

什麼是 GitDiagram？為什麼你需要它？

GitDiagram 是一個線上工具，它能將 GitHub 上的程式碼倉庫（Repository）轉換成視覺化的系統設計/架構圖。想像一下，你不用再埋頭苦讀一行又一行的程式碼，而是直接看到一個清晰的、可互動的圖表，清楚地呈現專案的各個組成部分以及它們之間的關係。是不是很棒？

GitDiagram 可以幫助你：

• 快速理解專案結構： 就算程式碼庫很大，也能迅速掌握專案的整體架構，省去大量的摸索時間。
• 方便導航： 點擊圖表上的元件，就能直接跳轉到對應的原始程式碼檔案或目錄，方便你深入研究。
• 提高學習效率： 對於想參與開源專案的新手來說，GitDiagram 絕對是一個加速學習、更容易做出貢獻的神器。
• 視覺化呈現： 將複雜的專案架構轉化成易於理解的圖表，方便團隊溝通和協作。

GitDiagram 的核心特色

GitDiagram 的核心特色可以歸納為以下幾點：

• 即時視覺化： 能夠快速將 GitHub 倉庫結構轉換成系統設計或架構圖。
• 互動性： 圖表上的元件可以點擊，直接連結到原始程式碼檔案和目錄。
• 快速生成： 採用 Claude 3.5 Sonnet (目前有可能已更換) 技術，能快速且準確地生成圖表。
• 客製化： 可以修改和重新生成圖表，加入客製化的指令。
• API 存取： 提供公開 API，方便整合到其他應用程式中（開發中）。

GitDiagram 的技術堆疊

GitDiagram 的背後，是一套精巧的技術組合：

• 前端： Next.js, TypeScript, Tailwind CSS, ShadCN
• 後端： FastAPI, Python, Server Actions
• 資料庫： PostgreSQL (with Drizzle ORM)
• AI： OpenAI o3-mini (目前有可能已更換)
• 部署： Vercel (前端), EC2 (後端)
• CI/CD： GitHub Actions
• 分析： PostHog, Api-Analytics

如何使用 GitDiagram？簡單三步驟，輕鬆上手！

使用 GitDiagram 非常簡單，即使你是程式新手，也能輕鬆上手。

方法一：直接在 GitHub URL 中替換文字

這是最簡單快速的方法：

1. 找到你想要分析的 GitHub 倉庫網址。 例如：`https://github.com/facebook/react`
2. 將網址中的 hub 替換成 diagram。 例如：`https://gitdiagram.com/facebook/react`
3. 按下 Enter 鍵，就能看到 GitDiagram 為你生成的互動式架構圖！

方法二：透過 GitDiagram 網站

1. 前往 GitDiagram 網站： https://gitdiagram.com/
2. 在搜尋框中輸入 GitHub 倉庫的網址，然後按下 “Generate Diagram” 按鈕。
3. 稍等片刻，就能看到 GitDiagram 為你生成的互動式架構圖！

小提示： 記得檢查網址是否正確，確保 GitDiagram 能夠正確抓取到 GitHub 倉庫的資訊。

GitDiagram 的背後原理：Prompt Engineering 的魔力

GitDiagram 的核心技術之一是 Prompt Engineering。它透過精心設計的提示詞（Prompts），引導 AI 模型從程式碼檔案樹和 README 文件中提取資訊，並進行分析，最終生成 Mermaid.js 格式的架構圖。

如果你對 Prompt Engineering 感興趣，可以研究 GitDiagram 專案中的 /backend/app/prompts.py 檔案，了解更多細節。

如何分析私有倉庫？

GitDiagram 也支援分析私有 GitHub 倉庫，方法如下：

1. 在 GitDiagram 網站的標頭中點擊 “Private Repos”。
2. 按照指示，提供一個具有 repo 權限的 GitHub 個人存取令牌（Personal Access Token）。

安全性提醒： 請妥善保管你的 GitHub 個人存取令牌，避免洩露給他人。

自架 GitDiagram：打造屬於你的專屬分析工具

如果你希望擁有更高的控制權和安全性，也可以選擇在本地自架 GitDiagram。以下是簡單的步驟：

1. 克隆 GitDiagram 倉庫：

   git clone https://github.com/ahmedkhaleel2004/gitdiagram.git
   cd gitdiagram
   

2. 安裝依賴：

   pnpm i
   

3. 設定環境變數（建立 .env 檔案）：

   cp .env.example .env
   

   編輯 .env 檔案，填入你的 Anthropic API 金鑰（如果有的話）和 GitHub 個人存取令牌（可選）。

4. 執行後端：

   docker-compose up --build -d
   

   日誌可在 docker-compose logs -f 中查看。FastAPI 伺服器將在 localhost:8000 上運行。

5. 啟動本地資料庫：

   chmod +x start-database.sh
   ./start-database.sh
   

   當提示生成隨機密碼時，輸入 yes。Postgres 資料庫將在 localhost:5432 上的容器中啟動。

6. 初始化資料庫 schema：

   pnpm db:push
   

   你可以使用 pnpm db:studio 查看和與資料庫互動。

7. 運行前端：

   pnpm dev
   

   現在你可以在 localhost:3000 上存取網站。你也可以在 backend/app/routers/generate.py 的 generate 函數裝飾器中編輯速率限制。

自架的好處：

• 更高的安全性： 你可以完全掌控資料和金鑰，避免洩露風險。
• 客製化： 你可以根據自己的需求修改程式碼，添加新的功能。
• 擺脫速率限制： 你可以調整或取消速率限制，更自由地使用 GitDiagram。

個人實作心得與錯誤排除指南

在嘗試使用 GitDiagram 的過程中，我遇到了一些小問題，在這裡分享給大家，希望能幫助大家少走彎路：

• API 金鑰錯誤： 如果你選擇使用 Anthropic API，請務必確認 API 金鑰是否正確，並且具有足夠的權限。
• 資料庫連線問題： 在自架 GitDiagram 時，可能會遇到資料庫連線問題。請檢查資料庫是否已正確啟動，以及 .env 檔案中的資料庫連線資訊是否正確。
• 圖表生成失敗： 有時候，GitDiagram 可能無法成功生成圖表。這可能是因為 GitHub 倉庫的結構太複雜，或者 README 文件中缺少必要的資訊。你可以嘗試簡化倉庫結構或修改 README 文件，然後重新生成圖表。
• 字體顯示問題： 有時候，圖表中的字體可能會顯示不正常。你可以嘗試更換字體或調整字體大小，看看能否解決問題。

GitDiagram 的未來發展

GitDiagram 仍在不斷發展中，未來可能會加入更多令人期待的功能，例如：

• 在圖表中加入 font-awesome 圖示。
• 實現類似 star-history.com 的嵌入式功能，讓圖表能夠隨著提交而逐步更新。

總結：GitDiagram，開啟開源專案探索之旅的鑰匙！

GitDiagram 是一個非常實用的工具，它能幫助你快速理解 GitHub 倉庫的結構，提高學習效率，更容易參與開源專案。無論你是程式新手還是經驗豐富的開發者，都值得嘗試一下。

現在就前往 https://gitdiagram.com/，體驗 GitDiagram 的魔力吧！如果你在使用過程中遇到任何問題，歡迎在留言區提問，我會盡力幫助大家！

貢獻

歡迎大家參與 GitDiagram 的開發！如果你有任何建議或想法，歡迎提交 Pull Request。

致謝

感謝 Romain Courtois 的 Gitingest 提供的靈感和樣式。

希望這篇文章對大家有所幫助！下次再見！

參考閱讀

https://github.com/ahmedkhaleel2004/gitdiagram