💬 Fuwari 加入 Twikoo 評論系統

#前言

Twikoo 不是「只貼一段 JS 就結束」的東西，它分成兩半：

部分	作用	你最後會拿到什麼
後端	存留言、管理留言、發信通知	`envId`，也就是 Twikoo 後端地址
前端	把留言框渲染到文章底部	一個 `Twikoo.astro` 元件

所以整個流程會長這樣：

先部署 Twikoo 後端。
拿到 envId。
在 Fuwari 建立評論元件。
把元件掛到文章頁底部。
部署網站，測試留言框是否出現。

這篇適合誰
你不需要先懂 Astro，也不需要先懂雲函數。只要你知道「檔案在哪裡」、「怎麼複製程式碼」、「怎麼部署網站」，就能照著做。

#你要先準備什麼？

開始前，先確認手上有這些東西：

一個正在使用的 Fuwari 部落格。
一個可以部署 Twikoo 後端的平台，例如 Netlify、Vercel、Hugging Face、自己的 VPS。
如果選 Netlify / Vercel / Hugging Face，通常還需要一個 MongoDB Atlas 資料庫。
一點點耐心，因為這種功能最容易錯在「路徑」、「環境變數」、「部署後沒有重新整理」。

推薦選擇
新手可以優先選 Netlify + MongoDB Atlas。Twikoo 官方文件對 Netlify 的步驟寫得比較完整，免費額度也比較夠一般個人博客使用。

#一、部署 Twikoo 後端

Twikoo 的留言資料不會存在你的 Fuwari 專案裡，而是存在 Twikoo 後端連到的資料庫裡。你可以把後端理解成一個「留言 API」。

#1.1 建立 MongoDB Atlas 資料庫

如果你選的是 Netlify、Vercel 或 Hugging Face 部署，通常會用 MongoDB Atlas 當資料庫。

操作重點只有三個：

註冊 MongoDB Atlas。
建立免費 Cluster。
取得連線字串，也就是 MONGODB_URI。

連線字串大概會長這樣：

1
mongodb+srv://使用者名稱:密碼@cluster0.xxxxx.mongodb.net/twikoo?retryWrites=true&w=majority

這串不能外流
MONGODB_URI 等於資料庫鑰匙。不要寫進 GitHub，不要放到前端程式碼，不要貼到文章裡。它只應該放在部署平台的環境變數。

#1.2 用 Netlify 部署 Twikoo

Netlify 的概念很簡單：你 fork 官方的 Twikoo Netlify 專案，Netlify 幫你把它部署成一個雲函數。

流程如下：

打開 Twikoo 官方的 twikoo-netlify 倉庫。
Fork 到自己的 GitHub。
到 Netlify 新增網站，選擇「Import an existing project」。
連到剛剛 fork 的倉庫。
在環境變數新增：

Key	Value
`MONGODB_URI`	你的 MongoDB Atlas 連線字串

部署完成後，進入 Netlify 給你的網址測試。如果畫面顯示 Twikoo 後端正常運行，就代表後端完成。

Netlify 的 envId 格式通常是：

1
https://你的站名.netlify.app/.netlify/functions/twikoo

把這串記下來，等一下要填進 Fuwari 的設定檔。

#二、在 Fuwari 增加 Twikoo 設定型別

接下來回到 Fuwari 專案。

先打開：

1
src/types/config.ts

在合適位置加入 Twikoo 的設定型別：

1
export type CommentConfig = {
2
  twikoo?: TwikooConfig;
3
};
4

5
export type TwikooConfig = {
6
  envId: string;
7
  region?: string;
8
  lang?: string;
9
};

這段的意思是：之後 config.ts 可以多一個 commentConfig，裡面可以填 Twikoo 的後端地址。

欄位	必填	說明
`envId`	是	Twikoo 後端地址
`region`	否	騰訊雲才常用，例如 `ap-guangzhou`
`lang`	否	指定語言，例如 `zh-TW`

#三、在 `config.ts` 填入 Twikoo 後端地址

打開：

1
src/config.ts

先把 CommentConfig 加進 import：

1
import type {
2
  CommentConfig,
3
  ExpressiveCodeConfig,
4
  LicenseConfig,
5
  NavBarConfig,
6
  ProfileConfig,
7
  SiteConfig,
8
} from "./types/config";

然後在檔案底部加入：

1
export const commentConfig: CommentConfig = {
2
  twikoo: {
3
    envId: "https://你的站名.netlify.app/.netlify/functions/twikoo",
4
    lang: "zh-TW",
5
  },
6
};

先不要急著改別的
這裡只要確認 envId 是你自己的 Twikoo 後端地址。不要填 MongoDB 連線字串，前端永遠不應該知道資料庫密碼。

#四、建立 Twikoo 前端元件

接下來建立資料夾：

1
src/components/comment/

然後新增檔案：

1
src/components/comment/Twikoo.astro

放入以下內容：

1
---
2
import { commentConfig } from "@/config";
3

4
interface Props {
5
  path: string;
6
}
7

8
const config = {
9
  ...commentConfig.twikoo,
10
  el: "#twikoo-comment",
11
  path: Astro.props.path,
12
};
13
---
14

15
<div id="twikoo-comment"></div>
16

17
<script define:vars={{ config }}>
18
  const TWIKOO_SCRIPT_ID = "twikoo-script";
19
  const TWIKOO_SCRIPT_SRC =
20
    "https://cdn.jsdelivr.net/npm/twikoo@1.7.11/dist/twikoo.min.js";
21

22
  function initTwikoo() {
23
    if (!window.twikoo) return;
24
    window.twikoo.init(config);
25
  }
26

27
  function loadTwikoo() {
28
    const existingScript = document.getElementById(TWIKOO_SCRIPT_ID);
29

30
    if (existingScript) {
31
      initTwikoo();
32
      return;
33
    }
34

35
    const script = document.createElement("script");
36
    script.id = TWIKOO_SCRIPT_ID;
37
    script.src = TWIKOO_SCRIPT_SRC;
38
    script.defer = true;
39
    script.onload = initTwikoo;
40
    document.body.appendChild(script);
41
  }
42

43
  document.addEventListener("DOMContentLoaded", loadTwikoo);
44
  document.addEventListener("astro:page-load", loadTwikoo);
45
  loadTwikoo();
46
</script>

這個元件做了三件事：

建立一個 <div id="twikoo-comment"></div> 當留言區容器。
動態載入 Twikoo 前端 JS。
載入完成後呼叫 twikoo.init(config)。

為什麼要鎖版本？
CDN 連結使用 twikoo@1.7.11，意思是固定載入 1.7.11 版。這樣 Twikoo 未來更新時，你的網站不會因為自動升版突然壞掉。

#五、建立評論入口元件

再新增：

1
src/components/comment/index.astro

內容如下：

1
---
2
import type { CollectionEntry } from "astro:content";
3
import { commentConfig } from "@/config";
4
import Twikoo from "./Twikoo.astro";
5

6
interface Props {
7
  post: CollectionEntry<"posts">;
8
}
9

10
const { slug } = Astro.props.post;
11
const path = `/posts/${slug}/`;
12
const enableTwikoo = Boolean(commentConfig.twikoo?.envId);
13
---
14

15
{enableTwikoo && (
16
  <section class="card-base p-6 mb-4">
17
    <Twikoo path={path} />
18
  </section>
19
)}

這一層看起來多此一舉，但它很有用：

以後想從 Twikoo 換成 Giscus，只改這個入口即可。
可以統一控制「有沒有設定 envId 才顯示留言區」。
文章頁只需要掛一個 <Comment />，不用知道底層細節。

#六、掛到文章頁底部

打開文章頁：

1
src/pages/posts/[...slug].astro

在 import 區加入：

1
import Comment from "@components/comment/index.astro";

找到文章內容、License、分享區塊後面的位置，把評論元件放進去。

如果你的文章頁原本是這樣：

1
<!-- comments -->
2
<Giscus />

可以改成：

1
<!-- comments -->
2
<Comment post={entry} />

不要同時開兩套評論
如果你原本已經有 Giscus，建議先二選一。Twikoo 和 Giscus 同時顯示不是不能用，但文章底部會很亂，讀者也不知道該在哪裡留言。

#七、部署並測試

改完後先在本地跑一次：

1
pnpm dev

打開任一篇文章，確認底部有沒有出現 Twikoo 留言框。

如果本地正常，再部署到正式站：

1
git add .
2
git commit -m "Add Twikoo comments"
3
git push

部署完成後，正式站再測一次：

打開任一篇文章。
滑到底部。
留一則測試留言。
點留言框右下角或管理入口，設定管理員密碼。

第一次管理密碼很重要
Twikoo 第一次進管理面板時會讓你設定管理員密碼。這不是網站登入密碼，而是 Twikoo 留言後台密碼，請另外記好。

#八、暗色模式看不清楚怎麼辦？

有些 Fuwari 主題在暗色模式下，Twikoo 的輸入框、文字或邊框可能對比不夠。

你可以先用最小 CSS 修一下：

1
#twikoo-comment {
2
  color: var(--text-90);
3
}
4

5
#twikoo-comment .tk-content,
6
#twikoo-comment .tk-preview,
7
#twikoo-comment textarea,
8
#twikoo-comment input {
9
  color: inherit;
10
}
11

12
#twikoo-comment textarea,
13
#twikoo-comment input {
14
  background: var(--card-bg);
15
}

如果你要更深度客製化，可以改用 Twikoo 的 twikoo.nocss.js，然後自己引入完整 CSS。不過新手不建議一開始就這樣做，先讓功能跑起來比較重要。

#九、常見錯誤排查

#留言框完全沒有出現

先檢查這幾件事：

src/pages/posts/[...slug].astro 是否真的有 <Comment post={entry} />。
src/config.ts 是否有 export commentConfig。
commentConfig.twikoo.envId 是否為空。
瀏覽器 Console 是否有 JS 錯誤。

#留言框出現，但送出失敗

通常是後端問題：

envId 填錯。
Netlify / Vercel 後端沒有部署成功。
MONGODB_URI 沒有設定。
MongoDB Atlas 的密碼、使用者、網路存取設定錯誤。

#本地正常，正式站不正常

優先檢查：

正式站是不是還沒部署到最新 commit。
部署平台是否有快取。
Twikoo 後端網址是否允許正式站網域呼叫。
如果使用騰訊雲，是否有設定 Web 安全域名。

#每篇文章留言混在一起

這通常代表 path 沒有正確傳入。

我們在 index.astro 裡使用：

1
const path = `/posts/${slug}/`;

這樣每篇文章都會有自己的評論路徑。只要你的文章網址也是 /posts/xxx/ 這種格式，就能正確分開。

#十、一張圖理解整體架構

1
讀者打開文章
2
    |
3
    v
4
Fuwari 文章頁載入 <Comment />
5
    |
6
    v
7
Twikoo.astro 載入 twikoo.min.js
8
    |
9
    v
10
twikoo.init({ envId, path, el })
11
    |
12
    v
13
Twikoo 後端接收請求
14
    |
15
    v
16
MongoDB 儲存 / 讀取留言

講白一點：

Fuwari 負責顯示文章。
Twikoo 前端負責顯示留言框。
Twikoo 後端負責處理留言。
MongoDB 負責保存留言。

把這四件事分清楚，排錯就不會亂。

#最後整理

整個接入流程可以濃縮成這份 checklist：

Twikoo 接好後，留言系統就會變成你網站的一部分。文章不再只是單向輸出，讀者可以直接在文章底下提問、補充、吐槽，技術文也會更像一個能持續更新的討論串。

#前言

#你要先準備什麼？

#一、部署 Twikoo 後端

#1.1 建立 MongoDB Atlas 資料庫

#1.2 用 Netlify 部署 Twikoo

#二、在 Fuwari 增加 Twikoo 設定型別

#三、在 config.ts 填入 Twikoo 後端地址

#四、建立 Twikoo 前端元件

#五、建立評論入口元件

#六、掛到文章頁底部

#七、部署並測試

#八、暗色模式看不清楚怎麼辦？

#九、常見錯誤排查

#留言框完全沒有出現

#留言框出現，但送出失敗

#本地正常，正式站不正常

#每篇文章留言混在一起

#十、一張圖理解整體架構

#最後整理

#參考資料

#三、在 `config.ts` 填入 Twikoo 後端地址