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

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

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

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

為什麼選擇 react-markdown？

Live Demo

直接渲染為 React 組件

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

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

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

插件生態也是一大亮點。你可搭配 remark-gfm 實現 GitHub 樣式（表格、待辦清單、刪除線等）、用 rehype-highlight 或 rehype-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 與設置

完整選項請見 官方文件。

Markdown 語法速查

# H1
## H2
### H3

- 無序項目
- 支持 * 或 + 書寫

1. 有序清單
2. 依序排列

粗體、斜體

連結文字

圖片標題

行內代碼

js<br>console.log('這是代碼區塊');<br>

> 這是引用

---
***

- [ ] 未完成
- [x] 已完成

總結

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

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