碰 Twilio 之前先停下來,看完這篇再行動:一個前輩的串接實錄
官方文件太繞?從我奮鬥兩個月的記憶裡,挖出來的 Twilio Video 避坑指南你是不是也曾在整合第三方服務時,看官方文件看到快睡著?

你是不是也曾在整合第三方服務時,看官方文件看到快睡著?
曾經,我也為此花了快兩個月的時間,在無數個坑裡打滾。 回頭看那段經歷,我發現官方文件解釋了每個 API 能做什麼,卻很少聊到在真實專案裡 該怎麼組合,更別提那些會讓你抓狂的各種狀況了。
這篇文章,就是我從記憶裡挖出來的一些心得和開發模式,希望能幫你少走一些我走過的冤枉路。
在這篇只會介紹串接 Twilio 最核心的部分!但基本上核心串接完成之後,其他部分難度就大降了。
以下用 Nextjs 撰寫虛擬碼 (Pseudocode)。
核心觀念:先搞懂規則,再上牌桌
動手前,有四個角色你一定要先認識,不然肯定會一團亂:
- Room(房間): 就是一個虛擬聊天室,大家都在這裡碰面,由 Twilio 的伺服器管著。
- Participant(參與者): 任何進來的人,包括你自己 (
LocalParticipant) 和其他人 (RemoteParticipant)。 - Track(軌道): 真正傳送畫面的數據流。你的攝影機畫面是一個
VideoTrack,麥克風聲音是AudioTrack。 - Access Token: 一張有時效、有權限的臨時房卡。前端不能拿萬能鑰匙(API Keys),只能憑這張房卡進門。
後端:蓋一個安全的「授權櫃檯」
第一步,也是最重要的,就是蓋一個安全的後端來發放「房卡」。用 Next.js 的 API Routes 來做這件事超方便。
注意:以下為虛擬碼 (Pseudocode),旨在說明概念,並非可直接執行的程式碼。
// 檔案位置: /api/generate-twilio-token
// 收到前端來的請求
function handler(請求) {
// === 安全第一 ===
// 這裡一定要先檢查,發請求的人是不是合法的登入使用者
// ... 你自己的使用者身份驗證邏輯 ...
// 從請求中拿出使用者名稱跟想進入的房間名
const userName = 請求.body.userName;
const roomName = 請求.body.roomName;
// === 呼叫 Twilio ===
// 1. 拿出存在伺服器環境變數裡、絕不外洩的 Twilio 金鑰
const twilioKeys = {
accountSid: process.env.TWILIO_ACCOUNT_SID,
apiKey: process.env.TWILIO_API_KEY_SID,
apiSecret: process.env.TWILIO_API_KEY_SECRET,
};
// 2. 用這些金鑰,向 Twilio SDK 要求一張新的 Access Token
const accessToken = createNewTwilioToken(twilioKeys, userName);
// 3. 告訴 Twilio,這張 Token 只能用在指定的房間
grantVideoAccess(accessToken, roomName);
// === 回傳結果 ===
// 把產生好的 JWT 格式 Token 回傳給前端
return response.json({ token: accessToken.toJwt() });
}前端:優雅地處理各種突發狀況
前端最麻煩的就是處理非同步事件。人隨時會進來、離開、斷線,我們得準備好。
1. 概念:用一個專屬 Hook 集中管理房間邏輯
我習慣把所有跟 Twilio 房間有關的髒活累活,都丟到一個自訂的 Hook (useTwilioRoom) 裡,讓 UI 元件保持清爽。
注意:以下為虛擬碼 (Pseudocode)。
// 檔案位置: /hooks/useTwilioRoom.js
function useTwilioRoom(token) {
// 我們需要管理的狀態:房間物件、所有參與者的列表
const [room, setRoom] = useState(null);
const [participants, setParticipants] = useState([]);
// 當拿到前端傳來的 token 後,執行連線
useEffect(() => {
if (!token) return;
// 概念:呼叫 Twilio SDK 的 connect 方法,傳入 token
const twilioRoom = connectToTwilio(token);
setRoom(twilioRoom);
setParticipants(twilioRoom.currentParticipants);
// === 這裡就是事件監聽的藝術 ===
// 監聽事件:當有「新的人」進來時
twilioRoom.on('participantConnected', (newParticipant) => {
// 概念:把新的參與者加到我們的 participants 狀態列表中
addParticipantToList(newParticipant);
});
// 監聽事件:當有「某個人」離開時
twilioRoom.on('participantDisconnected', (leavingParticipant) => {
// 概念:從 participants 狀態列表中移除這個人
removeParticipantFromList(leavingParticipant);
});
// 最重要的清理工作:當這個 Hook 被銷毀時 (例如使用者跳頁)
return () => {
// 概念:主動告訴 Twilio 我要離開房間了,釋放資源
disconnectFromRoom(room);
};
}, [token]);
// 把整理好的狀態回傳給 UI 元件使用
return { room, participants };
}2. 概念:讓每個參與者,都成為一個獨立元件
千萬別直接在 useEffect 裡操作 DOM,那在 React 裡是災難的開始。更好的方法是,讓每個參與者的畫面都由一個專屬的元件負責。
注意:以下為虛擬碼 (Pseudocode)。
// 檔案位置: /components/ParticipantView.js
function ParticipantView({ participant }) {
// 建立一個 ref,用來指向未來要放影像畫面的那個 div
const videoRef = useRef(null);
useEffect(() => {
// === 處理影音軌道 ===
// 概念:取得這個參與者發布的所有影音軌道
const allTracks = participant.tracks;
// 遍歷所有軌道
for (const track of allTracks) {
// 如果這個軌道是可見的 (subscribed)
if (track.isSubscribed) {
// 概念:把這個 track 的影像畫面,掛到 videoRef 這個 DOM 元素上
attachTrackToDOM(track, videoRef.current);
}
}
// === 同樣要監聽未來的新增與移除事件 ===
// participant.on('trackSubscribed', ...);
// participant.on('trackUnsubscribed', ...);
// === 清理工作 ===
return () => {
// 概念:當這個元件消失時,要把掛上去的畫面全部移除乾淨
detachAllTracksFromDOM(participant.tracks);
};
}, [participant]);
// 回傳一個容器,用來顯示這個參與者的畫面和名字
return (
<div className="participant-container">
<div ref={videoRef} className="video-wrapper" />
<p>{participant.identity}</p>
</div>
);
}結語
這段打造 Twilio 視訊功能的旅程,說實話,真的不容易。我一開始也跟大家一樣,把官方文件翻了個底朝天,但總覺得少了點什麼;接著跑去研究官方的範例專案,結果光是啟動就遇到一堆問題。
過程中,我找到一位印度開發者的版本,寫得清楚多了,給了我不少啟發,但離我想要的完整功能,始終差了那麼一步。
最終,我只能用最簡單也最有效的方法:直接去看 Twilio SDK 的 TypeScript 原始碼。我就這樣一行一行地追蹤、一個一個地摸索,像在拼湊一塊巨大的拼圖。直到某個瞬間,所有零散的觀念突然串連起來,我才終於打造出一個能穩定運作的視訊功能。
這趟旅程雖然艱辛,但也讓我真正體會到,追根究柢、直面源頭,才是解決複雜問題的最終王道。它證明了只要不放棄,再難的技術也能被我們一步步征服。
如果你想看看我更早期的奮鬥紀錄,可以參考這篇文章:
人生重構-Day29-再戰新產品-串接視訊功能-Twilio