React-markdown 完整實戰:用 React 優雅渲染 Markdown 的最佳實踐

作者: Calpa Liu
字數:1327
出版:2025 年 5 月 15 日
想在 React 應用中即時渲染並預覽 Markdown?這篇文章將徹底介紹 react-markdown 的安裝、用法、擴展性與最佳實踐,幫你打造高效的技術文檔體驗。

許多開發者在構建部落格、知識庫或協作平台時,常常面臨「如何在 React 專案中安全且優雅地渲染 Markdown?」的難題。傳統將 Markdown 轉換為 HTML 再用 dangerouslySetInnerHTML 插入,會有 XSS 風險、樣式難以自訂、互動性不足等問題。

為了解決這些痛點,react-markdown 應運而生:它能將 Markdown 內容直接解析為 React 組件,讓你安全渲染、靈活覆寫樣式與邏輯。無論是即時預覽、語法高亮,還是自訂元件外觀,都能高效實現。

本文將帶你從問題出發,逐步拆解 react-markdown 的核心用法,並以實例展示如何在現代 React 架構下,打造安全、可擴展、專業的 Markdown 呈現體驗。

為什麼選擇 react-markdown?

Live Demo
Live Demo
直接渲染為 React 組件
直接渲染為 React 組件

react-markdown 是 React 生態中最受歡迎的 Markdown 解析組件之一,開箱即用,無需複雜設定,即可精準渲染主流 Markdown 語法。你可以輕鬆建構高質感的技術文件、部落格、知識庫、即時預覽器等應用場景。

每一種 Markdown 標記(如標題、清單、連結、圖片、程式碼區塊等)都會自動對應為 React 組件。這讓你不僅能自訂各種元素的渲染邏輯(如覆寫 <a><img>、代碼區塊等),還能輕鬆加入 lazy loading、懶加載、佔位圖、甚至自定義交互,讓內容和體驗皆可高度擴展。

安全性方面,react-markdown 預設跳過 HTML 直寫,杜絕 XSS 等安全風險。你可透過 skipHtmlallowedElements 等選項細緻控制 HTML 的解析與允許範圍,兼顧彈性與安全。

插件生態也是一大亮點。你可搭配 remark-gfm 實現 GitHub 樣式(表格、待辦清單、刪除線等)、用 rehype-highlightrehype-prism 加入程式碼高亮、支援 Emoji、數學公式、甚至連結預覽等進階功能,滿足工程師與內容團隊的多元需求。

常見應用場景包括:

  • 技術部落格與知識文件系統(如 Next.js + MDX)
  • 即時 Markdown 編輯器與預覽工具
  • 支援語法高亮的 API 或產品說明頁
  • 論壇、社群平台的用戶內容渲染
  • 管理後台的靜態與動態內容預覽

react-markdown 讓你聚焦於內容本身,而非繁瑣的轉換與安全細節,幫助你高效打造現代化的內容前端體驗。

安裝步驟

在你的 React 專案中安裝:

npm install react-markdown

或使用 yarn:

yarn add react-markdown

基本用法

最簡單的用法只需一行:

import ReactMarkdown from 'react-markdown';

const markdown = `
# React-markdown Demo

- 支持列表
- **粗體**
- [外部連結](https://github.com/remarkjs/react-markdown)
`;

function App() {
  return <ReactMarkdown>{markdown}</ReactMarkdown>;
}

請注意:react-markdown@6.x 以後,Markdown 內容建議作為子元件傳入,而非 source 屬性。

即時渲染範例

你可以直接將 Markdown 字串渲染到任何 React 元素內:

import React, { useState } from 'react';
import ReactMarkdown from 'react-markdown';

function MarkdownEditor() {
  const [value, setValue] = useState('# Hello Markdown!');

  return (
    <div>
      <textarea
        value={value}
        onChange={e => setValue(e.target.value)}
        rows={8}
        cols={50}
      />
      <div className="preview">
        <ReactMarkdown>{value}</ReactMarkdown>
      </div>
    </div>
  );
}

透過 ReactMarkdown,你可以輕鬆實現 Markdown 到 React 組件的轉換,並根據需求自訂渲染邏輯。

進階功能與自訂渲染

以下是幾個進階功能的示例:

自訂 Markdown 元素對應的 React 元件

你可以覆寫渲染規則,例如將所有的連結開新視窗:

<ReactMarkdown
  components={{
    a: ({ node, ...props }) => <a {...props} target="_blank" rel="noopener noreferrer" />
  }}
>
  {markdown}
</ReactMarkdown>

支持 GFM、語法高亮等插件

要支持 GitHub Flavored Markdown(如表格、待辦清單等),你可以加裝插件:

npm install remark-gfm rehype-highlight

使用方式:

import remarkGfm from 'remark-gfm';
import rehypeHighlight from 'rehype-highlight';

<ReactMarkdown
  remarkPlugins={[remarkGfm]}
  rehypePlugins={[rehypeHighlight]}
>
  {markdown}
</ReactMarkdown>

常用 props 與設置

屬性/參數作用說明
childrenMarkdown 字串內容(必填)
className容器自訂 class
components自訂渲染對應元件(如自訂 aimg
remarkPluginsMarkdown 處理 plugin(如 GFM)
rehypePluginsHTML 處理 plugin(如語法高亮)
skipHtml是否跳過 HTML 標籤(預設 true,建議如此)

完整選項請見 官方文件

Markdown 語法速查

語法範疇Markdown 範例說明
標題
# H1
## H2
### H3
使用 # 表示不同層級的標題
無序清單
- 無序項目
- 支持 * 或 + 書寫
使用 -*+ 作為開頭
有序清單
1. 有序清單
2. 依序排列
數字後加點自動排序
粗體、斜體
粗體斜體
**粗體**_斜體_
連結
連結文字
[文字](網址)
圖片
圖片標題
圖片標題
![圖片說明](圖片網址)
行內程式碼
行內代碼
使用反引號(`)標記行內代碼
程式碼區塊
js<br>console.log('這是代碼區塊');<br>
三個反引號包住多行程式碼,可加語言類型
引用
> 這是引用
> 符號開頭標記引用
水平線
---
***
三個以上 -*
任務清單
- [ ] 未完成
- [x] 已完成
GFM 語法,方框加空格為未完成,加 x 為已完成
表格
標題A

總結

這篇文章最初於 2017 年撰寫,2025 年經由 ChatGPT 大幅重寫,內容更加完善並緊貼前端生態的最新發展。AI 工具的協助讓技術分享變得更高效,也讓教學內容更具時代性。

React-markdown 為 React 世界帶來輕量、靈活且安全的 Markdown 渲染解決方案。不論是用於部落格、知識庫、評論系統或技術文檔編輯器,都能大幅提升開發效率與用戶體驗。若你有更深入的應用需求,歡迎留言討論!

關於 Calpa

Calpa 擅長使用 TypeScriptReact.jsVue.js 建立 Responsive Website。

他積極參與開源社區,曾在 2019 年的香港開源大會上擔任講者,提供工作經驗和見解。此外,他也在 GitHub 上公開分享個人博客程式碼,已獲得超過 300 顆星星和 60 個分支的支持。

他熱愛學習新技術,並樂意分享經驗。他相信,唯有不斷學習才能跟上快速演變的技術環境。

熱門文章

最新文章

圖片管理中心
管理圖片資源
IP 查詢
快速查詢和定位 IP 地址的地理位置和相關信息
Python 運行器
無需後端、無需登入,只需打開瀏覽器即可運行 Python 代碼(由 Pyodide 提供支持)
封面圖生成器
自動創建適合各種平台的文章封面圖
原作(青山剛昌)產生器
一鍵創建原作(青山剛昌)的封面圖
日本色彩
探索和使用傳統日本色彩
部落格內容洞察儀表板
以視覺化儀表板方式追蹤文章成效、分享熱度與分類分布,協助創作者掌握內容表現。
蒙特卡羅估算 π
使用蒙特卡羅方法演示 π 值的估算過程
LLM
使用 LLM 模型進行聊天
活動圖生成器
一鍵創建活動的封面圖
Wagmi Card
一鍵創建 Wagmi 的封面圖
Facebook Quote
Facebook Quote
Music Macro Language (MML) Studio
用程式語法編寫旋律,用音符構築想像
Blurhash
一鍵創建 Blurhash
文字分類器
使用 MediaPipe TextClassifier 分類文字
前端工程師免費工具資源
前端工程師免費工具資源
後端工程師免費工具資源
後端工程師免費工具資源
全端工程師免費工具資源
全端工程師免費工具資源
Web3 工程師免費工具資源
Web3 工程師免費工具資源
紫微斗數排盤系統|結合 AI 的命盤性格與事業財務分析生成器
紫微斗數排盤工具,輸入生日與時辰,自動生成完整命盤分析提示(Prompt)。結合最專業紫微理論與 AI 助力,助你深入解析性格、事業、財務與人際課題。免費使用,適合命理師及紫微愛好者。
PixAI Prompt 組合器|快速打造可用於 AI 繪圖的語言拼圖
使用 PixAI 卻不會寫 prompt?這個工具幫你一鍵組裝角色、表情、風格語彙,輸出高品質繪圖提示語句(Prompt),可直接貼入 PixAI 使用。適合插畫師、創作者、AI 新手與 VTuber 角色開發者。