LIFF 開發教學 2026：Next.js 與 TypeScript 實作

# 用 LINE 的產生器建立新專案（範本中有 Next.js）
npx @line/create-liff-app

# 或在既有的 Next.js 專案中加入 SDK
npm install @line/liff@^2.31.2

# .env.local
NEXT_PUBLIC_LIFF_ID=1234567890-AbcdEfgh
LINE_LOGIN_CHANNEL_ID=1234567890

// components/liff-provider.tsx
"use client"

import { createContext, useContext, useEffect, useState, type ReactNode } from "react"
import type { Liff } from "@line/liff"

type Profile = Awaited<ReturnType<Liff["getProfile"]>>

type LiffState = {
  liff: Liff | null
  profile: Profile | null
  error: string | null
  ready: boolean
}

const initialState: LiffState = { liff: null, profile: null, error: null, ready: false }
const LiffContext = createContext<LiffState>(initialState)

// 每次載入頁面只初始化一次，即使 React 在開發模式下執行兩次 effect
let liffPromise: Promise<Liff> | null = null

function loadLiff(liffId: string): Promise<Liff> {
  liffPromise ??= import("@line/liff").then(async ({ default: liff }) => {
    await liff.init({ liffId, withLoginOnExternalBrowser: true })
    return liff
  })
  return liffPromise
}

export function LiffProvider({ liffId, children }: { liffId: string; children: ReactNode }) {
  const [state, setState] = useState<LiffState>(initialState)

  useEffect(() => {
    let cancelled = false
    loadLiff(liffId)
      .then(async (liff) => {
        const profile = liff.isLoggedIn() ? await liff.getProfile() : null
        if (!cancelled) setState({ liff, profile, error: null, ready: true })
      })
      .catch((err: unknown) => {
        const message = err instanceof Error ? err.message : String(err)
        if (!cancelled) setState({ ...initialState, error: message, ready: true })
      })
    return () => {
      cancelled = true
    }
  }, [liffId])

  return <LiffContext.Provider value={state}>{children}</LiffContext.Provider>
}

export const useLiff = () => useContext(LiffContext)

// app/(liff)/layout.tsx
import type { ReactNode } from "react"
import { LiffProvider } from "@/components/liff-provider"

export default function LiffLayout({ children }: { children: ReactNode }) {
  return <LiffProvider liffId={process.env.NEXT_PUBLIC_LIFF_ID!}>{children}</LiffProvider>
}

// components/profile-card.tsx
"use client"

import { useLiff } from "./liff-provider"

export function ProfileCard() {
  const { ready, error, profile } = useLiff()

  if (!ready) return <p>載入中…</p>
  if (error) return <p>LIFF 錯誤：{error}</p>
  if (!profile) return null

  return (
    <div className="flex items-center gap-3">
      {profile.pictureUrl && (
        <img src={profile.pictureUrl} alt="" width={48} height={48} className="rounded-full" />
      )}
      <p className="font-semibold">{profile.displayName}</p>
    </div>
  )
}

// lib/verify-user.ts（瀏覽器端）
import type { Liff } from "@line/liff"

// 送出 ID Token 而不是個人資料，由伺服器向 LINE 驗證
export async function getVerifiedUserId(liff: Liff): Promise<string> {
  const idToken = liff.getIDToken() // 需要 openid 權限範圍
  if (!idToken) throw new Error("沒有 ID Token：請確認 openid 權限範圍與登入狀態")

  const res = await fetch("/api/liff/verify", {
    method: "POST",
    headers: { Authorization: `Bearer ${idToken}` },
  })
  if (!res.ok) throw new Error(`驗證失敗：${res.status}`)
  const { userId } = (await res.json()) as { userId: string }
  return userId
}

// app/api/liff/verify/route.ts
export async function POST(request: Request) {
  const idToken = request.headers.get("authorization")?.replace(/^Bearer /, "")
  if (!idToken) return Response.json({ error: "Missing ID token" }, { status: 401 })

  const res = await fetch("https://api.line.me/oauth2/v2.1/verify", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      id_token: idToken,
      // 放置這個 LIFF 應用的 LINE Login 頻道的 Channel ID
      client_id: process.env.LINE_LOGIN_CHANNEL_ID ?? "",
    }),
  })
  if (!res.ok) return Response.json({ error: "Invalid ID token" }, { status: 401 })

  const payload = (await res.json()) as { sub: string; name?: string; exp: number }
  // payload.sub 就是驗證過的 LINE 使用者 ID，用它查詢或建立你的會員
  return Response.json({ userId: payload.sub })
}

import type { Liff } from "@line/liff"

export async function sendToChat(liff: Liff, text: string) {
  if (!liff.isInClient()) {
    alert("請從 LINE 聊天室開啟此頁面再傳送訊息。")
    return
  }
  try {
    await liff.sendMessages([{ type: "text", text }])
  } catch (err) {
    // 403：不是從聊天室開啟、使用者未同意 chat_message.write，
    // 或應用是從「最近使用的服務」重新載入
    console.error("sendMessages failed", err)
  }
}

export async function shareProduct(liff: Liff) {
  if (!liff.isApiAvailable("shareTargetPicker")) return

  const result = await liff.shareTargetPicker(
    [
      {
        type: "flex",
        altText: "雞腿便當 NT$120",
        contents: {
          type: "bubble",
          hero: {
            type: "image",
            url: "https://example.com/images/chicken-set.jpg",
            size: "full",
            aspectRatio: "20:13",
            aspectMode: "cover",
          },
          body: {
            type: "box",
            layout: "vertical",
            contents: [
              { type: "text", text: "雞腿便當", weight: "bold", size: "lg" },
              { type: "text", text: "NT$120", color: "#06C755" },
            ],
          },
          footer: {
            type: "box",
            layout: "vertical",
            contents: [
              {
                type: "button",
                style: "primary",
                color: "#06C755",
                // 透過分享目標選擇器傳送的訊息只能使用 URI 動作
                action: { type: "uri", label: "立即訂購", uri: "https://liff.line.me/1234567890-AbcdEfgh/menu/42" },
              },
            ],
          },
        },
      },
    ],
    { isMultiple: true },
  )

  if (result) console.log(`[${result.status}] 已分享`)
  else console.log("使用者關閉了選擇器")
}

export async function askToAddFriend(liff: Liff) {
  const { friendFlag } = await liff.getFriendship() // 需要 profile 權限範圍
  if (!friendFlag) await liff.requestFriendship() // LIFF v2.28.0 以上，僅限 Full 大小
}

export async function scanTableQr(liff: Liff) {
  const { value } = await liff.scanCodeV2() // 先在 Console 開啟「Scan QR」
  return value
}

// components/app-shell.tsx
"use client"

import type { ReactNode } from "react"
import { useLiff } from "./liff-provider"

export function AppShell({ children }: { children: ReactNode }) {
  const { liff, ready } = useLiff()
  if (!ready || !liff) return <p>載入中…</p>

  // 在外部瀏覽器中，withLoginOnExternalBrowser 已把使用者導向 LINE Login
  // 這裡只負責隱藏需要 LIFF 瀏覽器的功能
  const inLine = liff.isInClient()
  return (
    <main style={{ paddingBottom: "env(safe-area-inset-bottom)" }}>
      {children}
      {!inLine && <p>在 LINE 中開啟此頁面，才能分享或傳到聊天室。</p>}
    </main>
  )
}

export async function shareCurrentPage(liff: Liff) {
  // https://liff.line.me/{liffId}/{path} 會開啟 Endpoint URL 底下相同的路徑
  const url = await liff.permanentLink.createUrlBy(window.location.href)
  await navigator.clipboard.writeText(url)
}

npm install -g @line/liff-cli
liff-cli channel add 1234567890   # 會要求輸入 Channel secret
liff-cli serve --liff-id 1234567890-AbcdEfgh --url http://localhost:3000/

# 要在手機上開啟時，改用 ngrok 公開，而不是本機代理
NGROK_AUTHTOKEN=your-token liff-cli serve --liff-id 1234567890-AbcdEfgh --url http://localhost:3000/ --proxy-type ngrok