LIFF v2開発の落とし穴：liff.init()エラーの解決法とCORS対策完全ガイド

LIFF（LINE Front-end Framework）アプリ開発を始めたばかりのエンジニアが、真っ先に壁にぶつかるのが liff.init() の失敗とCORSエラーです。ローカル開発環境で画面が真っ白のまま進まなかったり、ブラウザのコンソールに赤いエラーログが並んだりして、開発のスタートダッシュでつまずいてしまう方も多いのではないでしょうか。本記事では、LIFF v2系の開発において避けては通れないこれらのエラーについて、ローカル開発環境でのデバッグ手順と本番環境へのデプロイ時にハマるポイントを徹底解説します。

liff.init() が失敗する代表的な原因とデバッグ手法

LIFFアプリ開発において、liff.init() はすべての起点となる心臓部です。このメソッドの実行が完了しなければ、ユーザー情報の取得やメッセージ送信など、LINEプラットフォームの各種APIを利用することはできません。

初期化エラーを防ぐためには、まず適切なエラーハンドリングを実装することが重要です。以下のTypeScriptの実装サンプルをご覧ください。

import liff from '@line/liff';
 
async function initializeLiff() {
  try {
    // VITE_LIFF_ID は環境変数から取得
    await liff.init({ liffId: import.meta.env.VITE_LIFF_ID });
    console.log('LIFFの初期化に成功しました');
    
    if (!liff.isLoggedIn()) {
      liff.login();
    }
  } catch (error) {
    console.error('LIFFの初期化に失敗しました:', error);
    // 画面上にエラーメッセージを表示するなどのフォールバック処理
  }
}
 
initializeLiff();

liff.init() が失敗する場合、最も頻繁に見られる原因は「エンドポイントURLとLIFF IDの不一致」です。LINE Developersコンソールの「LIFF」タブに登録したエンドポイントURLと、実際にブラウザで開いているURLが完全に一致している必要があります。末尾のトレイリングスラッシュ（/）の有無や、http と https の違いだけでもエラー弾かれてしまうため注意が必要です。

また、公式ドキュメントによれば、LIFF SDK（v2系）はLINE内のブラウザ（LIFFブラウザ）だけでなく、Google ChromeやSafariといった外部ブラウザでも動作します。しかし、ローカルのHTMLファイルを直接開く形式（file:// プロトコル）では初期化に失敗するため、必ずローカルサーバーを立ち上げて検証を行う必要があります。

エラーオブジェクトに出力される code や message を確認することで、これらの設定漏れなのか、あるいはネットワークの遮断によるものなのかを切り分けることができます。

ローカル開発を阻むCORSエラーの正体と回避策

liff.init() の壁を越えた後に待ち受けているのが「CORS（Cross-Origin Resource Sharing）エラー」です。LIFFアプリのフロントエンド（例：http://localhost:5173）から、自社で開発しているバックエンドAPI（例：http://localhost:3000）へ非同期通信を行う際に、ブラウザの同一生成元ポリシーによって通信がブロックされる現象です。

ローカル開発環境でこのCORSエラーを回避するための効果的なアプローチは、主に2つ存在します。

1. ngrokを利用してセキュアなトンネルを構築する

フロントエンドとバックエンドのドメインを共通化、あるいは外部からアクセス可能なHTTPS化されたURLを発行するために ngrok や localtunnel を利用します。特にLINEのWebhook開発なども並行して行う場合、ngrokは必須級のツールと言えます。

# フロントエンドのポート(5173)を外部公開する例
ngrok http 5173

ここで発行された https://xxxxxx.ngrok.app のようなURLをLINE DevelopersコンソールのエンドポイントURLに設定することで、LINEアプリ上での動作確認もスムーズに行えるようになります。

2. ビルドツールのプロキシ機能を活用する

もしフロントエンドの開発にViteやWebpackを使用している場合、開発サーバーのプロキシ機能を設定するのが最も手軽な解決策です。フロントエンドからのAPIリクエストを、開発サーバー側でバックエンドへ転送（プロキシ）することで、ブラウザ上は同一オリジンへのリクエストとして処理させます。

以下は Vite を使用した場合の vite.config.ts の設定例です。

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
 
export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      // /api から始まるリクエストをバックエンド(ポート3000)へ転送
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
});

この設定により、CORSの設定をバックエンド側にハードコードすることなく、フロントエンド側の工夫のみでローカル開発を進行させることが可能になります。

本番環境へのデプロイ時にハマるポイント

ローカル開発環境で完璧に動作していても、いざ本番環境（VercelやAWSなど）にデプロイして実機で確認すると、予期せぬエラーが発生することが多々あります。ここでは「よくあるハマりどころ」を解説します。

HTTPS通信の必須化と証明書エラー

LINEヤフー株式会社が提供するLINEプラットフォームの仕様として、LIFFアプリのエンドポイントURLは「HTTPS（TLS 1.2以上）」であることが厳格に求められます。自社サーバーなどでSSL証明書を設定する際、中間証明書の設定が漏れていると、外部ブラウザでは開けるのに、LINEアプリ内のLIFFブラウザで開いたときだけ画面が真っ白になる現象が起きることがあります。本番デプロイ後は、SSLチェックツールなどで証明書チェーンが正しく構築されているかを確認してください。

LIFFブラウザの強力なキャッシュ

コードを修正して再デプロイしたにもかかわらず、LINEアプリ上で開くと画面が更新されないことがあります。これはLIFFブラウザのキャッシュが原因で古いスクリプトが読み込まれていると考えられます。 解決策として、LIFF URL（https://liff.line.me/xxx-yyy）の末尾にクエリパラメータ（例：?ver=1.0.1）を付与してキャッシュバスティングを行うか、LINEアプリの「設定 > トーク > データの削除」からキャッシュをクリアする運用を試してください。

開発チャネルのステータス公開忘れ

最後に、意外と見落としがちなのがLINE Developersコンソールでの「公開」設定です。チャネルのステータスが「開発中」のままだと、そのチャネルの管理者・テスター権限を持つアカウントでしかLIFFアプリを開くことができません。一般ユーザーに提供する前には、必ずコンソール上部からステータスを「公開済み」に変更しておきましょう。

まとめ

LIFF v2系におけるアプリ開発では、初期の liff.init() エラーとCORS問題が大きな障壁となりがちです。しかし、LINE Developersコンソールの設定（エンドポイントURLとLIFF ID）を慎重に見直し、Viteのプロキシ設定やngrokといったツールを適切に導入することで、これらの課題は確実に解決できます。

エラーが発生した際は推測でコードを修正するのではなく、ブラウザの開発者ツールを活用してエラーログを読み解くことが大切です。公式ドキュメントと照らし合わせながら一つずつ原因を潰していくことが、スムーズなLIFF開発への一番の近道となります。ぜひ本記事の設定例やデバッグ手法を参考に、快適な開発環境を構築してください。