把網頁匯入 Figma 時圖示為什麼會不見

什麼都到了，就是圖示沒到。空盒子、黑方塊，或者原本箭頭位置上的小長方形。原因有四種，是哪一種決定了能不能修。

你把一個頁面搬進 Figma，什麼都到了，就是圖示沒到。原本箭頭、放大鏡和外部連結小標記的位置，只剩空方框、黑塊，或者什麼都沒有。

這不是一個 bug。網頁上畫圖示有四種完全不同的做法，每一種壞掉的方式也不一樣。弄清楚你面對的是哪一種，就知道能不能修、怎麼修。

四種圖示，四種失敗方式

1. 內嵌 SVG

最容易的一種。圖示直接寫在 HTML 裡，是一個 <svg> 元素，path 就在裡面。任何會讀 DOM 的轉換工具都看得到幾何形狀，可以直接交給 Figma 一個向量。

這種情況失敗，通常是轉換工具壓平了什麼：用 <use> 引用了別處定義的 symbol、掛著 CSS filter、或者用 currentColor 填色但脫離繼承環境後失去了顏色。

2. SVG 精靈圖

一個檔案把所有圖示存成 <symbol>，用到圖示的地方只放一個引用。

<svg class="icon"><use href="/icons.svg#chevron-down" /></svg>

在網頁上很有效率，對天真的轉換工具卻是隱形的。DOM 裡那個元素內部沒有 path。照字面讀，得到的是一個空的 <svg>，所以精靈圖常常變成尺寸正確的空白盒子。

要解決它，得順著引用去取精靈圖檔案，依 id 找到 symbol，再把幾何形狀嵌進來。如果精靈圖在另一個來源上，這個請求本身還得先被允許。

3. 圖示字型

圖示是字型裡的一個字元。Font Awesome、Material Icons 以及各家自建的圖示字型都是這樣做的：一個帶 class 的元素、一個 ::before 偽元素，以及一個裝著 Unicode 私用區碼位的 content 屬性。

.fa-search::before { content: "\f002"; }

有兩件事會出錯。第一，圖示住在偽元素裡，而偽元素不在 DOM 中——元素樹怎麼走都找不到它。第二，就算轉換工具把它當成文字抓到了，進到 Figma 也是那個字元本身，而如果你電腦上沒裝這套圖示字型，Figma 就畫它的替代字形：一個空方框，或某個不相干的字。

匯入的頁面裡滿是小長方形，這個經典症狀就是這麼來的。

4. CSS 遮罩圖示

值得單獨談，因為它越來越常見，而且失敗的樣子看起來像成功。元素完全沒有內容，只有背景色和一個遮罩。

.icon {
  background-color: currentColor;
  -webkit-mask-image: url(/icons/search.svg);
  mask-size: contain;
}

形狀在遮罩圖裡，顏色在元素上。讀背景的轉換工具拿到的是一個圖示顏色的實心矩形。所以這類往往變成黑色或彩色的方塊，而不是什麼都沒有：顏色對了，形狀不見了。

用 VitePress 做的文件網站大量使用這個模式。我們最早就是這樣撞上的：有人回報某個文件網站的圖示全都被匯成了黑方塊。

轉換工具為什麼會漏掉

因為要涵蓋這四種，得做四件不同的事，其中三件都不只是讀 DOM。

• 精靈圖需要把被引用的檔案取回來，再把 symbol 取出。
• 圖示字型需要讀偽元素的樣式、解析碼位，把字形畫成向量，而不是當作文字傳下去。
• 遮罩圖示需要取回遮罩圖，並把元素的顏色套用到得到的形狀上，而不是套在一個矩形上。

只順著 DOM 走一遍、把找到的東西複製下來的轉換工具，能搞定第一種，其餘三種會靜默失敗。這是常態，不是特例。

怎麼判斷自己是哪一種

開啟頁面，在圖示上按右鍵，檢查。三十秒就看得出來。

Snapture 分別怎麼處理

四種都處理。「我們支援圖示」這句話每個工具都會說，所以具體寫清楚怎麼做的。

• 內嵌 SVG 以向量幾何原樣通過。如果某個 SVG 複雜到 Figma 的匯入器會卡住——巢狀遮罩、濾鏡、foreignObject——就改為點陣化。這是刻意的降級，不是靜默失敗。
• 精靈圖 透過順著 <use> 引用、取回精靈圖、把被引用 symbol 的幾何形狀連同正確的 viewBox 一起嵌入來解決。
• 圖示字型 透過讀偽元素的計算 content 來辨識，並把字形畫成圖形，而不是當作字元交給 Figma。結果不取決於你有沒有裝那套圖示字型。
• CSS 遮罩圖示 透過取回遮罩圖、把元素自身的顏色套用到得到的形狀上來解決，所以遮罩圖示是以真實顏色的圖示形態進來的，而不是一個填色矩形。

在實測頁面公布的那次量測裡，Linear 的首頁產出了 215 個向量節點，Stripe 是 153 個。其中大部分都是圖示的工作，能不能編輯和檔案上有沒有破洞，差別就在這裡。

如果檔案裡的圖示已經壞了

點陣化的黑方塊沒辦法修，形狀資訊根本沒進到檔案裡。用能解決你這一類情況的工具重新匯入。

唯一的例外是圖示字型。如果它們是以文字字元進來的，而你本機裝了那套字型，Figma 在你這邊會畫得沒問題——但對任何沒裝這套字型的人來說，檔案就是壞的。與其交出一個只有自己看起來正常的檔案，還是重新匯入比較好。

English · 한국어 · 日本語 · 简体中文 · 繁體中文 · Español · Português · Français · Deutsch · Русский · Italiano · Bahasa Indonesia