Markdown Emoji 表情符號：語法、速查表與平臺相容性指南

寫 Markdown 文件的時候，加個合適的 emoji 表情能讓內容更有表現力——README 裡用 🚀 表示「快速開始」，提交資訊裡用 ✅ 表示任務完成，筆記裡用 ⚠️ 標記注意事項。

但問題來了：markdown emoji 到底怎麼輸入？為什麼我在 GitHub 上寫 :smile: 能變成 😄，換到別的平臺卻原樣顯示？這篇文章把 markdown emoji 的幾種用法、常用速查表、以及平臺相容性一次性講清楚。無論你是在 GitHub 寫 README、在部落格平臺發文章，還是用 VS Code 寫筆記，都能找到適合你的方法。

Markdown 中的 Emoji：三種輸入方法

在 Markdown 裡用 emoji，說到底就三種方式：直接複製貼上 emoji 字元、用 shortcode 簡碼語法、用 Unicode 編碼。三種方法各有適用場景，下面逐一說明。

方法一：直接複製貼上（最簡單，相容性最廣）

最直接的方式就是把 emoji 當普通文字，直接貼上到 Markdown 檔案裡：

今天心情不錯 😄，分享一下學習心得！

TODO 列表：
- ✅ 完成 Markdown 基礎語法
- 🔄 學習 markdown emoji 表情符號
- ⭐ 寫一篇教學

渲染效果：

今天心情不錯 😄，分享一下學習心得！

TODO 列表：

• ✅ 完成 Markdown 基礎語法
• 🔄 學習 markdown emoji 表情符號
• ⭐ 寫一篇教學

怎麼快速輸入 emoji？

• macOS：按 Control + Command + Space，調出 emoji 選擇面板
• Windows 10/11：按 Win + .（Windows 鍵 + 句號鍵），開啟 emoji 面板
• 手機：直接用系統自帶鍵盤的 emoji 頁面
• 線上複製：造訪 Emojipedia 或 emoji-all，搜尋後複製

說實話，我日常寫文件 80% 的場景用的就是這種方式——簡單粗暴，在哪都能用。因為 emoji 本質上就是 Unicode 字元，只要你的 Markdown 渲染器能處理 UTF-8 文字（基本上所有現代渲染器都支援），直接貼上就完事了。

不過這個方法也有個不太方便的地方：如果你經常需要輸入同一些 emoji，每次都要調出面板找半天，效率不太高。這時候 shortcode 語法就派上用場了。

方法二：Shortcode 簡碼語法（GitHub 等平臺專屬）

很多平臺支援用 :名稱: 的格式插入 emoji，這種寫法叫 emoji shortcode（簡碼）。比如：

歡迎使用 :rocket: Markdown Emoji :heart_eyes:

常用標記：
:white_check_mark: 已完成
:x: 未完成
:warning: 注意事項
:bulb: 小提示
:star: 推薦

在 GitHub 上渲染後會變成：

歡迎使用 🚀 Markdown Emoji 😍

常用標記： ✅ 已完成 ❌ 未完成 ⚠️ 注意事項 💡 小提示 ⭐ 推薦

shortcode 的好處是：純文字可讀性好。看原始碼時 :white_check_mark: 比 ✅ 更容易理解意圖，在 commit message 和 issue 評論裡用起來很方便。

但 shortcode 最大的問題是平臺依賴。GitHub 支援的 shortcode 列表來自 gemoji 庫，不同平臺支援的列表不完全一樣。我在 CSDN 上測試 :smile: 可以正常渲染，但在簡書和掘金上就原樣顯示文字——這一點後面相容性部分會詳細說。

順便提一句，如果你用 VS Code 寫 Markdown，可以裝一個 Markdown Emoji 外掛，它能在預覽中解析 shortcode，這樣寫的時候就能看到實際效果。

方法三：Unicode 編碼（相容性最保險）

每種 emoji 在 Unicode 標準中都有一個唯一的編碼。你可以用 HTML 實體的方式插入：

笑臉：😀
紅心：❤
火箭：🚀
對號：✅

渲染效果：😀 ❤️ 🚀 ✅

這種方式的優勢是：所有支援 HTML 的 Markdown 渲染器都能正確處理。不過說實話，日常寫文件誰也記不住這些編碼，實際用的場景比較少。主要在一些不支援 shortcode、又不太方便直接貼上的特殊環境裡有用武之地。

參考：Unicode Consortium 維護著完整的 emoji 編碼列表，可在 Unicode Full Emoji List 查詢。

三種方法對比

我的建議是：日常寫東西直接貼上就行；寫 commit message 或 issue 用 shortcode 更規範；Unicode 編碼知道有這個方法就好，真碰到需要的時候再查。

Markdown Emoji 常用速查表

下面整理了一份常用的 emoji shortcode 速查表。寫文件最常用的基本都在這裡了，完整列表可以參考 GitHub Emoji Cheat Sheet 或 emoji-cheat-sheet.com。

表情與手勢

標記與符號

專案管理常用

在 commit message 中使用 emoji

很多團隊喜歡在 commit message 前加 emoji 來標明提交類型，這是一種常見的 Conventional Commits 變體：

✨ feat: 新增 markdown emoji 速查功能
🐛 fix: 修復 emoji shortcode 渲染異常
📝 docs: 更新 emoji 使用文件
🎨 style: 調整 emoji 對齊方式
♻️ refactor: 重構 emoji 解析邏輯
🧪 test: 添加 emoji 渲染測試案例
🚀 release: v2.0.0 正式發佈

這種方式在 Markdown All in One 專案的貢獻規範中就有使用，原始碼可讀性比純文字好很多。

平臺相容性詳解

前面提到 shortcode 不是所有平臺都支援，這裡做個詳細的對比。這個表格是我結合 Markdown Guide 官方文件、GitHub 說明文件以及實際測試整理的：

為什麼 shortcode 在某些平臺不生效？

這是因為 shortcode 不是 Markdown 核心規範的一部分。John Gruber 在 2004 年設計 Markdown 時根本沒有考慮 emoji（那時候 emoji 還沒走出日本）。: 包裹的寫法是 GitHub 在 GFM（GitHub Flavored Markdown）中引入的擴充語法，後來被 GitLab 等平臺跟進。

所以如果你在掘金或簡書寫 :smile:，渲染器不認識這個語法，就會原樣顯示為 :smile: 文字。

靜態網站生成器怎麼開啟 emoji 支援

如果你用靜態網站生成器（如 Hugo、Jekyll），shortcode 預設可能不生效，需要額外設定：

Hugo：在設定檔中開啟 emoji 處理器：

enableEmoji: true

Jekyll：安裝 jemoji 外掛：

# Gemfile
gem 'jemoji'

# _config.yml
plugins:
  - jemoji

Hexo：安裝 hexo-filter-github-emojis 外掛：

npm install hexo-filter-github-emojis --save

開發者整合：在自己的 Markdown 解析器中支援 Emoji

如果你在開發一個 Markdown 相關的應用，需要讓解析器支援 emoji，這裡介紹幾個常用的方案。

markdown-it-emoji（Node.js）

markdown-it 是最受歡迎的 Markdown 解析器之一，它有專門的 emoji 外掛：

import markdownit from 'markdown-it';
import { full as emoji } from 'markdown-it-emoji';

const md = markdownit();
md.use(emoji);

// 渲染 :smile: 為 😄
const result = md.render('Hello :smile:');
// 輸出: <p>Hello 😄</p>

外掛提供三種設定模式：

• full：包含所有 Unicode emoji（約 1800+）
• light：只包含常用 emoji（約 300 個）
• bare：不預置任何 emoji 資料，需要你自己提供對映表

參考：markdown-it-emoji npm 文件

Python-Markdown + PyMdown Extensions

Python 使用者可以用 PyMdown Extensions 的 emoji 擴充套件：

import markdown
from pymdownx import emoji

md = markdown.Markdown(extensions=['pymdownx.emoji'])
result = md.convert('Hello :smile:')

一個需要注意的坑：資料庫儲存

有一次我幫同事排查一個問題，他在 MySQL 資料庫裡存帶 emoji 的文章內容時報錯了。原因很簡單：MySQL 的 utf8 字元集最多支援 3 位元組的字元，而大多數 emoji 需要 4 位元組。

解決方法是把表的字元集改成 utf8mb4：

ALTER TABLE articles CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

這個問題在 PostgreSQL 和 SQLite 中不存在，它們預設就支援完整的 Unicode。但如果你用 MySQL，這一點一定要提前注意，不然存到 emoji 的時候才發現就晚了。

常見問題

為什麼我的 emoji 顯示為方框或問號？

這通常是因為：

1. 字型不支援：系統的字型缺少對應的 emoji 字形。Windows 7 及更早版本對 emoji 的支援很差
2. 編碼問題：檔案沒有儲存為 UTF-8 編碼
3. 資料庫字元集：如上面提到的，MySQL 需要使用 utf8mb4

Markdown emoji shortcode 有沒有完整的列表？

有的。最權威的參考是：

• GitHub 官方支援的 emoji 列表
• Unicode Full Emoji List
• Emojipedia — 按關鍵字搜尋最方便

怎麼在 Markdown 表格 中使用 emoji？

直接用就行，emoji 在表格中和其他文字沒有區別：

| 狀態 | 任務 |
|------|------|
| ✅ | 完成 Markdown 表格語法 |
| 🔄 | 學習 markdown emoji |
| ⏳ | 掌握 [Markdown 連結](/markdown/link語法/) |

Shortcode 和直接貼上哪個更好？

看場景。寫 Markdown 程式碼區塊 旁邊的註釋或個人筆記，直接貼上效率更高；寫 commit message、issue、PR 描述這些需要長期維護的團隊內容，shortcode 的可讀性優勢更明顯。在不確定平臺支援的情況下，直接貼上是最安全的選擇。

參考來源

• Markdown Guide - Extended Syntax — 確認 emoji 不屬於 Markdown 核心規範
• GitHub gemoji — GitHub emoji shortcode 對映庫
• Unicode Full Emoji List — Unicode 官方 emoji 編碼列表
• markdown-it-emoji — markdown-it emoji 外掛文件
• PyMdown Extensions — Python Markdown emoji 擴充套件
• Material for MkDocs — MkDocs emoji 設定文件
• Stack Exchange - Support Emoji in Markdown — 社群對 shortcode 支援的討論

emoji 語法本身沒幾行，但坑都在細節裡——shortcode 在哪些平臺能用、資料庫怎麼存、靜態網站怎麼設定，這些才是實際寫東西時真正會碰到的問題。希望這份指南能幫你少走些彎路。如果你對 Markdown 註釋 或其他 Markdown 語法也有疑問，可以看看這個系列的其他文章。