語法：和連結只差一個字元
- 語法只有
一種，和連結的差別只在開頭那個驚嘆號。 - Markdown 只存路徑，不存檔案本身，所以破圖幾乎都是路徑問題，不是語法問題。
- 純 Markdown 完全沒有寬度設定，要調尺寸只能改用 HTML 的
<img>標籤。 - 同一個相對路徑，在 GitHub、靜態網站建置與本機預覽三種環境可能得到三種結果。
整個語法就這麼一行：
三個組成部分
開頭的 ! 代表「把它嵌進來，不是連過去」。方括號裡放替代文字（alt text），小括號裡放路徑或網址。少打驚嘆號就會得到文字連結而不是圖片，這是最常見的打錯方式，也是建議先弄懂連結語法的理由。
小提醒：想把語法原樣秀出來又不讓它變成圖片，請包進程式碼區塊。反引號會把裡面所有語法字元關掉，驚嘆號也不例外。
加上標題（title）
路徑後面加一段引號文字，會變成 HTML 的 title 屬性，桌面瀏覽器會在滑鼠停留時顯示提示。多數人直接省略它，理由很實際：觸控裝置不會顯示、螢幕閱讀器處理方式不一致、搜尋引擎也不看。它適合放照片出處，別拿來放讀者非知道不可的內容。
它會變成什麼
<img src="images/bike.jpg" alt="一台紅色腳踏車靠在紅磚牆邊">底下所有行為都由這一行推導而來。Markdown 從不複製、上傳或內嵌檔案本身，它只存一個參照。所以圖片壞掉幾乎一定是路徑壞了，不是語法錯了。兩種語言的關係請看 Markdown 與 HTML 的比較。
替代文字到底是給誰看的
替代文字不是圖說，也不是檔名，它有兩個任務。螢幕閱讀器會唸出它來取代圖片，所以對視障讀者而言，替代文字就是那張圖。而當檔案 404 或 CDN 被防火牆擋掉時，瀏覽器也會把它印出來當備援。
寫出圖片「顯示了什麼」
拿它跟  比一比：前者讓看不到圖的人知道自己錯過什麼，後者等於什麼都沒說。三個習慣就能解決大半問題：
- 描述內容，不要描述檔案。「每月註冊數長條圖」永遠勝過「chart.png」。
- 不要寫「一張圖顯示」。輔助軟體本來就會先告訴使用者這是圖片。
- 長度控制在一個詞組。一句話就夠了，寫成一整段那叫圖說。
圖表和示意圖還有一條額外規則。如果圖片承載了內文沒提到的資訊，就把結論本身寫進替代文字，因為圖片是 Markdown 文件裡唯一無法被當成純文字閱讀的元素。
小提醒：當重點是數字而不是畫面時，請直接寫成 Markdown 表格，不要貼表格截圖。表格在任何閱讀環境都看得懂、搜尋得到，也複製得走。
什麼時候應該留空
純裝飾用的圖片，方括號應該留空。這不是偷懶而是正確做法：空的替代文字等於告訴螢幕閱讀器跳過沒有意義的東西。反之寫成 ![分隔線]，只會讓聽讀的使用者莫名聽到「分隔線」三個字。拿掉這張圖若讀者毫無損失，就留空。
相對路徑與絕對網址
絕對網址以 https:// 開頭，搬到哪裡都讀得到，代價是得仰賴一台可能不屬於你的主機。相對路徑則是相對於 Markdown 檔案當下的位置解析。圖片因此會跟著 Git 儲存庫走，每個分支、每個 fork 都看得到 - 直到你把同一段 Markdown 貼到沒有那個資料夾的地方為止。
 同層資料夾下的 img/
 效果相同，./ 只是裝飾
 往上一層，再進 assets/
 從根目錄算起，也最容易出事
 只要能連網就沒問題同一個路徑，在三種環境裡的下場
相對路徑讓人頭痛，是因為「相對於什麼」在每個工具裡的答案都不一樣：
| 你寫的路徑 | GitHub 儲存庫頁面 | 靜態網站建置（Hugo、Jekyll、Astro） | 本機預覽（VS Code） |
|---|---|---|---|
img/build.png | 相對於 .md 檔案解析，正常顯示。 | 通常會壞：產出頁面的網址層級和原始檔不同。 | 只要資料夾真的在旁邊就正常。 |
../assets/build.png | 正常，文件放在子資料夾時很常這樣寫。 | 會壞。建置產物裡沒有對應原始目錄的上一層。 | 正常。 |
/img/build.png | 相對於儲存庫根目錄解析。在 github.com 上可以，clone 下來就死。 | 這才是正確寫法：開頭的斜線代表已發布網站的根目錄。 | 相對於工作區資料夾解析，會給你錯誤的安全感。 |
https://cdn.example.com/x.png | 正常，會經過 GitHub 的圖片快取代理。 | 正常。 | 有網路就正常。 |
img/My Photo.png | 壞掉。空格會把路徑截斷。 | 壞掉。 | 壞掉。 |
兩條規則就能涵蓋大多數專案
在儲存庫的 README 裡，用相對於檔案的路徑；在靜態網站裡，把圖片放進 static 或 public，再用開頭帶斜線的網站根路徑引用。這兩種寫法在完整指南裡都有成品範例可以對照。
注意：同一個專案別把兩種寫法混用，也別把「本機預覽正常」當成證據。VS Code 會把開頭的斜線對到工作區資料夾，讓你一路自我感覺良好到部署那一刻。
參照式圖片與可點擊的圖片
當 CDN 網址是一長串八十個字元的雜湊值和查詢字串，直接寫在內文裡會毀掉原始碼的可讀性。參照式寫法可以把網址集中到檔案最後：
改版之後流量翻倍：
![2025 年流量圖表][chart]
[chart]: https://cdn.example.com/assets/8f2a/traffic-2025.png "每月工作階段數"這樣寫有三個好處：
- 標籤對應定義時不分大小寫，寫成
[Chart]一樣找得到[chart]。 - 定義可以放在文件的任何位置，讀者完全看不到它。
- 同一個定義能被任意多張圖重複使用，適合在五個地方出現的商標。
參照式連結用的是同一套機制，兩者也共用同一個好習慣：標籤請照內容命名，不要照它在檔案裡的順序命名。
讓圖片可以點擊
[](https://ci.example.com/project)把圖片包進連結，圖片就成為連結的內容。由內往外讀： 是圖片，外面那層 [...](...) 是連結。GitHub 上每一排徽章、每一張「點開看大圖」的縮圖靠的都是這個組合。
調整尺寸：Markdown 做不到的事
Markdown 的圖片語法裡沒有寬度也沒有高度，沒有簡寫，也沒有屬性可以放。圖片一律以原始像素尺寸顯示，這就是為什麼一張沒處理過的手機截圖可以佔滿整份 README。想指定尺寸，就必須走出 Markdown。變通做法有三種，依可攜性由高到低排列。
1. 放進去之前先把檔案縮小
最無趣的答案就是最好的答案。一張寬 900 像素的 PNG 載入更快、列印正常，在任何渲染器裡都能用。它不需要特殊語法，所以沒有東西能把它濾掉，也沒有東西會忽略它。
2. 改用原生 HTML 的 img 標籤
<img src="docs/settings.png" alt="設定頁面" width="420">
<p align="center">
<img src="docs/logo.svg" alt="專案標誌" width="180">
</p>這是 GitHub 上的標準答案，也是最接近「通用」的做法。幾乎所有允許 HTML 的渲染器都吃這一招：GitHub、GitLab、VS Code 與多數靜態網站產生器。有三個細節決定它會不會乖乖聽話：
- 只設定
width，高度會等比例跟著縮放，寫成width="50%"這種百分比也可以。 - 標籤請單獨放一行，上下各留一行空行。
- HTML 區塊內部的 Markdown 不會被處理，所以別在裡面再塞其他語法。
注意：嚴格的渲染器與會過濾 HTML 的發布系統會直接把標籤清掉，圖片不是變小，而是整張消失。這也是「不如直接把檔案縮小」的另一個理由。哪些工具允許什麼，Markdown 與 HTML 有整理。
3. 查詢字串，以及 GitHub 真正支援的東西
查詢字串會原封不動傳給存放圖片的伺服器，只有那台伺服器看得懂時才有作用。Cloudinary、imgix 這類圖片 CDN 就樂於即時幫你縮圖：
GitHub 只認得一個真正有用的參數 ?raw=true，作用是把儲存庫的網頁網址變成檔案本身：
從檔案頁面的網址列直接複製貼上而變成破圖時，這就是解法：blob 網址回傳的是 HTML 頁面，不是圖片。等效的直連寫法是 raw.githubusercontent.com/acme/docs/main/img/chart.png。GitHub 沒有寬度參數，?w=400 會被直接忽略。倒是有個片段技巧：加上 #gh-dark-mode-only 或 #gh-light-mode-only，就能依深淺色主題顯示不同的圖。
各家編輯器的自訂寫法
好幾個工具各自發明了尺寸語法，沒有一個是標準：
- Obsidian 吃
。 - Typora 與 markdown-it-imsize 吃
。 - Pandoc 吃
{width=50%}。
換個地方就變成一團看得見的垃圾字元：私人筆記隨你用，要發布的內容請避開。要不要採用這些自家擴充，Obsidian 指南裡有更完整的權衡。
圖片檔案到底該放哪裡
選擇圖片放哪，其實是在選擇「圖片消失的時候誰負責」。連結失效不是危言聳聽：圖床改條款、免費方案收攤，2019 年還好好的網址，今天就是一個破圖。
| 選項 | 適合場景 | 失效風險 | 老實說的取捨 |
|---|---|---|---|
放在儲存庫資料夾（docs/img/） | README、專案文件 | 極低 | 有版本、可審查、離線也能看。缺點是撐大儲存庫體積，二進位檔的 diff 也毫無意義。 |
| 拖進 GitHub issue 或留言 | 回報問題、隨手截圖 | 中等 | 零成本、貼上就有網址，但檔案在你的儲存庫之外。clone 下來或搬到別的平台就什麼都看不到。 |
靜態網站的 static/ 或 public/ | 部落格、文件網站 | 極低 | 隨網站一起部署，網址完全自己掌握。必須用根路徑寫法，因此在儲存庫頁面裡預覽不出來。 |
| 物件儲存或圖片 CDN（S3、R2、Cloudinary） | 大圖、大量圖片、需要即時縮圖 | 低，前提是帳單有繳 | 快、可縮放、容量無虞。要花錢，也多一個得記得續約的服務。 |
| imgur 這類免費圖床 | 論壇貼文、用完即丟的分享 | 高 | 免費又即時。但條款會變、舊圖會被清、可能封鎖外連，公司網路也常擋掉。 |
| 直接外連別人的網頁 | 沒有適合的場景 | 極高 | 未經同意消耗別人的頻寬，而對方隨時可以改名、刪除，或把圖換成任何東西。 |
只要東西在 Git 儲存庫裡，就把圖片一起 commit 進去。這是唯一能保證圖片和文字永遠待在一起的做法，而這正是純文字格式值得使用的理由本身，完整論述請見什麼是 Markdown。
小提醒：每個專案的圖片集中放在同一個資料夾，例如 docs/img/。圖片四散正是「搬動一個檔案就弄壞半份 README」的原因，集中之後修起來只要一次取代。
SVG、GIF 與各種檔案格式的差異
語法本身不管檔案格式，它只是寫出一個 src。能不能顯示，完全取決於瀏覽的那一端。
- PNG 與 JPEG 到哪裡都能用。截圖和圖表用 PNG，照片用 JPEG。
- 動態 GIF 到處都能用而且預設就會播放，是展示一小段操作流程的標準做法。長度請控制在幾秒內，一個 20 MB 的 GIF 對所有人都是災難。
- SVG 在 GitHub、GitLab 和瀏覽器裡都能顯示，放大到任何尺寸都不糊，適合標誌與示意圖。SVG 裡的 script 會基於安全考量被清除，而且有些渲染器完全拒絕 SVG。
- WebP 與 AVIF 檔案比 PNG 小很多，現行瀏覽器和 GitHub 都支援，但較舊的工具鏈仍然吃不下。
- PDF 與影片不是圖片。寫
只會得到破圖，不會變成播放器。請改用一般的連結語法指向它們，或用 GitHub 的上傳框把影片拖進去，它會自動轉成播放器。
拿不定主意時：有文字的畫面選 PNG，照片選 JPEG。這兩種格式幾十年來在每個工具裡都能用，也不需要任何備援。各平台到底渲不渲染圖片，語法速查表裡有對照。
常見錯誤與修法
檔名裡有空格
錯誤： 
修正： 
也可以：
也可以：解析器碰到第一個空格就停手。百分比編碼或角括號可以救回既有檔案，但把檔名改成連字號才是讓問題不再發生的解法。
大小寫敏感
在伺服器上壞掉： 
磁碟上的檔案： img/logo.pngmacOS 和 Windows 的檔案系統預設不分大小寫，負責建置與服務網站的 Linux 伺服器則分得一清二楚。於是本機預覽完美的頁面，一上線每張圖都是破的。統一一套命名慣例 - 所有素材一律小寫加連字號 - 這一整類 bug 就會消失。
中文輸入法打出全形括號
錯誤： ！［圖表］（img/chart.png）
修正： 中文輸入法會產生全形標點，而 Markdown 只認得半形的 ASCII 字元。替代文字本身寫什麼語言都可以，但包住它的那四個標點符號不行。打語法前先切回半形，或者先把標點打好再把文字貼進去。
漏掉驚嘆號，以及 blob 網址
錯誤： [截圖](img/app.png) 會變成文字連結
修正： 
錯誤： 
修正： 這兩個都是一個字元的差距。前者少了標記，後者則是指向網頁而不是指向網頁背後的那個檔案。
其餘症狀的排查表
| 你看到的現象 | 常見原因 | 修法 |
|---|---|---|
| 該出現圖片的地方變成文字連結 | 漏掉開頭的 ! | 補上驚嘆號 |
| GitHub 上破圖，自己電腦上正常 | 檔名大小寫，或貼到 blob 頁面網址 | 大小寫完全對齊，或加上 ?raw=true |
| 正式網站破圖，儲存庫頁面正常 | 路徑相對於檔案，而不是網站根目錄 | 把檔案移到 static/，路徑改成斜線開頭 |
| 替代文字出現，圖片始終載不出來 | 那個路徑上根本沒有檔案 | 把網址單獨貼到瀏覽器分頁打開 |
| 整行原樣印成文字 | 輸入法打出的全形括號 | 四個標點符號改用半形重打 |
怪平台之前先照這張表走一遍。網址錯的話一打開就是 404，網址對的話問題就出在你的 Markdown 上。更精簡的入門說明請見如何在 Markdown 中插入圖片。
相容性資料驗證日期
常見問題
Markdown 可以調整圖片大小嗎？
用 Markdown 語法不行。請改用原生 HTML 標籤，例如 <img src="a.png" alt="..." width="420">，GitHub 和多數渲染器都支援；直接把檔案本身縮小再放進來更保險。像  這種寫法只在發明它的那個工具裡有效。
為什麼我的圖片在 GitHub 上顯示成破圖？
三個常見兇手：相對路徑相對錯了資料夾、檔名大小寫對不上，或是你貼的是 blob 頁面網址而不是原始檔網址。Linux 伺服器很在意大小寫，你的筆電不在意。先在 blob 網址後面加上 ?raw=true，再把網址單獨打開確認檔案真的存在。
替代文字什麼時候應該留空？
純裝飾的圖片就該留空。空的方括號等於告訴螢幕閱讀器跳過這張圖，對分隔線或花紋而言這正是對的做法。只要圖片承載任何意義，就把讀者會錯過的東西描述出來。
圖片在每個平台的行為都一樣嗎？
Markdown 可以嵌入影片嗎？
不行，Markdown 完全沒有影片語法，寫  只會得到一張破圖，不是播放器。GitHub 是值得知道的例外：把影片檔直接拖進 issue、pull request 或 README，它會渲染成播放器，但那是 GitHub 的平台功能，不是 Markdown 的能力。其他地方只剩兩條路：寫原生 HTML 的 <video> 標籤（多數平台基於安全會直接濾掉），或是放一張縮圖，再用連結語法把它指向影片。
延伸閱讀
立即使用編輯器
立即使用編輯器