gRPC-Webとは？ブラウザからgRPCを呼ぶ仕組みとプロキシ構成・採用判断を解説

ブラウザのfetchやXMLHttpRequestからは、gRPCが前提とするHTTP/2のフレームやトレーラーを直接触れません。gRPC-Webは、その届かない部分を迂回するために定められた別のワイヤ形式で、Protocol Buffersのスキーマと生成済みクライアントをそのままブラウザ側へ持ち込めます。ただし扱えるRPCはUnaryとサーバストリーミングだけで、多くの構成では前段にEnvoyなどのプロキシが要ります。この記事では、二つのモードの違い、生成から通信までの実装要件、プロキシを置く構成と置かない構成、Connectやトランスコーディングとの選び分け、そして採用を見送るべき条件までを2026年8月時点の一次情報で整理しました。

まとめ｜gRPC-Webを採用してよい条件と先に決めるプロキシ構成の要件

先に結論を置きます。gRPC-Webが効くのは、バックエンドが既にgRPCで動いていて、同じprotoファイルからブラウザ側のクライアントも生成したい場合だけです。バックエンドがgRPCでないなら、ブラウザ対応のためにgRPC-Webを持ち込む理由はありません。

採用前に決めておく項目は二つです。ひとつは前段の構成で、Envoyのgrpc_webフィルタを挟むのか、ASP.NET Coreのようにサーバ自身で受けるのか、Connect対応サーバに寄せるのかを最初に固定します。もうひとつはRPCの形で、クライアントから連続してメッセージを送る設計が要件に入っていれば、その時点でgRPC-Webは候補から外れます。

版の現在地も判断材料に入ります。クライアント実行時ライブラリのgrpc-webはnpmで2.1.0、GitHubの最新リリースタグは2.0.2（2025年9月17日）です。直前の1.5.0が2023年11月9日なので、およそ1年10か月動きが止まったのち2025年8月末に2.0.0でまとめて更新された経緯があります。この更新間隔を許容できる体制かどうかを、採否と同時に確認してください。

gRPC-Webの定義とブラウザがgRPCを直接呼び出せない技術的な理由

gRPC-Webは新しいRPCの仕組みではなく、既存のgRPCサービスをブラウザから呼ぶための別のワイヤ形式です。何が削られているかを先に押さえると、後段の制約がそのまま説明できます。

ブラウザからHTTP/2のフレームとトレーラーへ届かないという制約

gRPCはHTTP/2の上に組まれ、ステータスコードをレスポンス末尾のトレーラーで返します。Microsoft Learnの「ブラウザー アプリでの gRPC の使用」は、ブラウザからgRPCサービスを直接呼び出せない理由を、gRPCがHTTP/2の機能を使うのに対し、ブラウザにはgRPCクライアントを支えるだけのWeb要求の制御手段が無いためだと説明しています。

ブラウザが公開しているのはfetchやXMLHttpRequestといった高水準のAPIだけです。個々のフレームを組み立てたり、トレーラーを読み出したりする経路がありません。gRPC-Webはここを、HTTP/1.1でも運べる本文フォーマットへ置き換え、トレーラー相当の情報を本文の末尾に埋め込む形で解決しています。gRPC本体の仕組みやRESTとの違いを先に確認したい場合は、gRPCとは？仕組み・RESTとの違い・UDP/TCPの扱いを実装例つきで解説を土台として読んでください。

grpcwebtextとgrpcweb｜二つのワイヤ形式とContent-Typeの差

gRPC-Webにはモードが二つあり、コード生成時にどちらを選ぶかで対応できるRPCが変わります。既定はbase64符号化のgrpcwebtextです。

Content-Typeの実値は、grpcwebtextが application/grpc-web-text、grpcwebが application/grpc-web+proto です。base64は本文をおよそ4/3に膨らませます。転送量を抑えたいならgrpcwebが有利ですが、そちらはサーバストリーミングを扱えません。ストリーミングを1本でも使う予定があるならgrpcwebtextに寄せ、全RPCが単発の応答で済むと確定してからgrpcwebへ切り替える順序が安全です。モードを後から変えるとブラウザ側の生成コードを作り直すことになります。

Unaryとサーバストリーミングのみという RPC方式の対応範囲

公式READMEが明示しているとおり、gRPC-Webが対応するのはUnary RPCとサーバ側ストリーミングRPCの二つだけです。クライアント側ストリーミングと双方向ストリーミングは未対応のまま残っています。

この制約は実装の都合ではなく、ブラウザ側の送信経路そのものに由来します。リクエスト本文を少しずつ送り続ける手段が全ブラウザで揃っていないため、仕様として先に閉じてある形です。つまり、チャットの入力を送り続ける、センサ値を継続的に上げる、といった要件はgRPC-Webでは満たせません。ここが方式選定の最初の分岐になります。

クライアント実装の手順｜protoからブラウザで呼び出すまでの生成と設定

実装の中身は、スキーマからコードを生成し、生成されたクライアントに接続先とメタデータを渡すだけです。詰まるのは生成そのものより、通信の周辺条件のほうが多くなります。

protoc-gen-grpc-webで生成するクライアントコードと版の選択

ブラウザ側の生成には、protoc本体に加えてprotoc-gen-grpc-webプラグインを使います。npmで公開されているprotoc-gen-grpc-webの最新公開は1.5.0で、実行時ライブラリのgrpc-webは2.1.0です。生成プラグインと実行時ライブラリで版系列がずれている点は、依存を固定するときに引っかかりやすいので先に把握しておいてください。

1. サービスとメッセージを定義したprotoファイルを用意する
2. protocにprotoc-gen-grpc-webを与え、モードと出力形式（JavaScriptかTypeScript定義付きか）を指定して生成する
3. 生成されたクライアントとgrpc-web実行時ライブラリをフロントのビルドへ取り込む
4. 接続先のエンドポイントを渡してクライアントを組み立て、メソッドを呼ぶ

protoファイル側の書き方そのものはProtocol Buffersとは？protoファイルの書き方と採用判断を実装者向けに解説で扱っています。gRPC-Web側で追加になるのは、生成時のモード指定と、後述する通信要件だけです。なお2.0.0（2025年8月30日）でprotobufが27.1へ上がり、コード生成が新APIへ書き換えられ、Editionsへの対応が入りました。1.5.0からの移行では生成物の差分を必ず確認してください。

CORSでgrpc-statusとgrpc-messageを露出させる設定の要点

gRPC-Webは通常のHTTPリクエストとしてブラウザから出ていくため、オリジンが異なればCORSの制約をそのまま受けます。公式のbrowser-features文書は、必要な条件として三点を挙げています。Authorizationヘッダを通すためのAccess-Control-Allow-Credentialsへの対応、メソッドをPOSTとプリフライトのOPTIONSに限定すること、そしてgrpc-statusとgrpc-messageをJavaScriptから読めるよう露出させることです。

三点目を落とすと症状が分かりにくくなります。通信自体は200で終わるのに、クライアントがステータスを読めずエラー内容が空になる、という形で出るためです。CORSのプリフライトや許可ヘッダの一般論はCORSとは？仕組み・プリフライト・サーバー設定例・エラー解決を実装目線で解説にまとめてあるので、設定の書き方はそちらを参照してください。

メッセージ単位の圧縮とデッドライン指定で実装が詰まりやすい箇所

サーバ間のgRPCで当たり前に使っている機能が、そのままは持ち込めない箇所があります。代表がメッセージ単位の圧縮です。公式文書は、JavaScript側での圧縮・解凍が高コストになるという理由から、ストリームされるリクエストとレスポンスのメッセージ単位圧縮に対応しないと明記しています。転送量を削りたい場合は、HTTP層のgzipやbrotliで受けるか、そもそもgrpcwebのバイナリモードを選ぶ判断になります。

もうひとつがデッドラインとキャンセルの扱いです。ブラウザ側から呼び出しを打ち切っても、前段のプロキシとバックエンドへ意図どおり伝わるかは構成に依存します。長時間のサーバストリーミングを流す設計なら、経路上のアイドルタイムアウトと合わせて実測してください。ここを詰めずに本番へ出すと、原因の切り分けが難しい切断として現れます。

サーバ側の構成｜Envoyのgrpc_webフィルタと代替プロキシの選び方

gRPC-Webの本体はワイヤ形式の変換です。誰がその変換を担うかで構成が三通りに分かれます。

envoy.filters.http.grpc_webを挟む標準構成と経路上の条件

既定の構成は、ブラウザとgRPCサーバの間にEnvoyを置く形です。Envoyはenvoy.filters.http.grpc_webというHTTPフィルタを標準で備えていて、HTTP/1.1で届いたgRPC-Web呼び出しをHTTP/2のgRPC呼び出しへ変換してバックエンドへ渡します。Envoyが既定として挙げられている理由は、トレーラーを正しく扱えるプロキシが限られるためです。Envoyの最新リリースは2026年7月14日公開のv1.39.0で、フィルタ自体は長く安定して提供されています。

選択肢はEnvoyだけではありません。gRPC-Web Go Proxy、Apache APISIX、nginxのgRPC-Webモジュールも公式に挙げられています。既にAPI前段でリバースプロキシやゲートウェイを運用しているなら、そこにgRPC-Web変換を寄せられるかを先に確認してください。前段に置く部品の役割分担はAPIゲートウェイとは？役割・機能とリバースプロキシ／サービスメッシュとの違い・導入判断を解説で整理しています。

プロキシを置かない構成｜ASP.NET Core組み込みとGoプロキシ

変換をサーバ自身に持たせる構成も選択肢です。.NETにはgRPC-Webの組み込みサポートがあり、ASP.NET CoreのgRPCサービスであれば前段にEnvoyを立てずにブラウザからの呼び出しを受けられます。Goであれば、変換をライブラリとしてHTTPハンドラに挟む方式が使えます。

プロキシを1段減らせるのは運用上の利点ですが、代わりにアプリケーション側が変換の責任を持ちます。バックエンドが複数言語で構成されているなら、各サービスに同じ対応を入れるより、前段にEnvoyを1つ置いて集約したほうが管理は軽くなります。単一言語・単一サービスならサーバ組み込み、多言語・複数サービスならプロキシ集約、という切り分けが実務的です。

Connect・gRPC JSONトランスコーディングとの選び分けの判断基準

ブラウザからgRPCバックエンドへ届く経路は、gRPC-Webだけではありません。ここが選定の本題になります。

Connect-ES 2.1系がgRPC-Web互換で提供する範囲と移行の判断

Connectは、gRPC互換を保ちながらHTTP/1.1でも素直に扱えるよう設計されたプロトコルとその実装群です。TypeScript向けの@connectrpc/connect-webはnpmで2.1.2が最新で、Connectプロトコルに加え、createGrpcWebTransportを使えばgRPC-Web互換の通信も同じクライアントから行えます。

判断はこうなります。バックエンドを触れず、既存のgRPCサーバとプロキシ構成をそのまま使うならgRPC-Webのままで十分です。一方、これからブラウザ向けの経路を新設するなら、Connect対応サーバへ寄せてプロキシを1段省く構成を先に検討してください。生成物がTypeScriptとして扱いやすく、デバッグ時にリクエストをそのまま読める点も効いてきます。Connect自体の位置づけはConnect（connectrpc）とは？gRPC・RESTとの違いと使い方をわかりやすく解説で解説しています。

gRPC JSONトランスコーディングでREST化を選ぶ条件と代償

三つ目の経路が、gRPCサービスをJSONのREST APIとして露出させるトランスコーディングです。.NETでは.NET 7以降で使え、protoファイルにHTTPのメタデータを注釈するとRESTful APIが自動生成されます。ブラウザ側はgRPCを知る必要がなく、生成クライアントも要りません。

代償は二つあります。Protocol Buffersのバイナリ表現による転送効率が失われること、そしてprotoにHTTPマッピングの注釈という別の関心事が入ることです。フロントが社内チームで型共有の価値が高いならgRPC-WebかConnect、外部の不特定クライアントにも開くならトランスコーディング。この線で分けると迷いが減ります。

ブラウザ対応の四方式を並べた選定表と実務で先に見るべき判断条件

四つの経路を、ブラウザ側の生成物・クライアントからの連続送出・前段に要る追加要素で並べると次のようになります。

先に見るべきは連続送出の列です。ここが要件に入っているなら上三つは全て落ち、WebSocketとは？仕組み・ハンドシェイクからNode.js実装・運用の判断まで実装者向けに解説で扱っている方式か、双方向を扱える別のトランスポートを検討することになります。連続送出が不要なら、次にバックエンドの既存構成を見て、gRPCが動いていればgRPC-WebかConnect、動いていなければ通常のREST/JSONで十分という順で絞れます。

gRPC-Webを見送るべき三つの条件と運用継続に必要な体制の判断

ここは言い切ります。gRPC-Webは万能な選択肢ではなく、外すべき条件がはっきりしています。

クライアントストリーミングの必要性など採用を見送る三つの条件

次のいずれかに当てはまるなら採用しないでください。

• クライアントから連続してメッセージを送る要件がある（仕様として未対応で、回避策は擬似的なものにしかならない）
• バックエンドがgRPCで動いていない（ブラウザ対応のためだけにgRPC化するのは投資に見合わない）
• 前段のプロキシを増やせない、かつサーバ側に変換を組み込めない（変換の担い手がいない構成では成立しない）

とくに二つ目は判断を誤りやすい箇所です。「型安全にAPIを呼びたい」という動機だけであれば、バックエンドがRESTのままでもOpenAPIからのクライアント生成で十分です。gRPC-Webの利点はスキーマ共有そのものではなく、既存のgRPC資産をブラウザまで延ばせる点にあります。資産が無い状態で導入すると、プロキシ運用とコード生成という手間だけが残ります。

生成物の版固定とCI管理という運用を継続するための体制の要件

採用するなら、protoファイルからの生成をCIに組み込み、生成物をレビュー対象に含める運用まで込みで設計してください。生成プラグインと実行時ライブラリの版がずれると、動くけれど型が合わない状態に入り込みます。protoc-gen-grpc-webが1.5.0、grpc-webが2.1.0という現状のずれは、まさにその管理を要求しています。

更新頻度も見ておく必要があります。1.5.0（2023年11月）から2.0.0（2025年8月）まで、およそ1年10か月リリースが空きました。この間隔でも許容できるのは、protoの変更を自分たちで管理でき、依存を固定したまま運用できるチームです。スキーマ駆動のAPI設計や、既存gRPCサービスとフロントの接続を含めて設計から任せたい場合は、API開発・システム連携で相談を受け付けています。

よくある質問

gRPC-Webの導入検討でよく挙がる質問を、仕様と公式ドキュメントの記載にもとづいて整理しました。

gRPC-WebとgRPCは何が違うのですか？

プロトコルの目的は同じですが、ワイヤ形式が別物です。gRPCはHTTP/2の上で動き、ステータスをトレーラーで返す仕組みです。gRPC-Webはブラウザから扱えるようHTTP/1.1でも運べる本文形式に置き換え、トレーラー相当の情報を本文末尾へ埋め込みます。この差のため、gRPC-Webの呼び出しはどこかでgRPCへ変換する必要があり、Envoyのgrpc_webフィルタやサーバ組み込みの機能がその役割を担う構成です。対応するRPCの範囲も、gRPCの4種類に対しgRPC-Webは2種類に絞られます。

gRPC-Webにプロキシは必ず必要ですか？

必須ではありませんが、変換を担う何かは必要です。標準構成はEnvoyを前段に置く形で、ほかにgRPC-Web Go Proxy、Apache APISIX、nginxのモジュールが公式に挙げられています。一方、ASP.NET CoreにはgRPC-Webの組み込みサポートがあり、この場合は追加のプロキシを立てずにサーバ自身が受ける構成です。単一言語・単一サービスならサーバ組み込み、複数サービスが並ぶならプロキシへ集約する切り分けが扱いやすくなります。

grpcwebtextとgrpcwebはどちらを選ぶべきですか？

サーバストリーミングを使う可能性が少しでもあるならgrpcwebtextです。grpcwebはバイナリのprotobufをそのまま運ぶため転送量で有利ですが、対応するのはUnaryのみで、サーバストリーミングを扱えません。grpcwebtextはbase64符号化のぶん本文がおよそ4/3に膨らみます。全RPCが単発の応答で済むと確定してからgrpcwebへ切り替える順序であれば、後戻りの手戻りを小さくできます。

双方向ストリーミングをブラウザで実現するにはどうすればよいですか？

gRPC-Webでは実現できません。クライアント側ストリーミングと双方向ストリーミングは未対応のまま残っており、これはブラウザの送信経路の制約に由来する仕様上の線引きです。双方向のやり取りが要件なら、WebSocketのように連続送出を前提とした方式か、双方向ストリームを扱えるトランスポートを選んでください。単発の要求と長めの応答という形に要件を組み替えられる場合に限り、サーバストリーミングで代替できます。

gRPC-WebとConnectはどちらを新規採用すべきですか？

これから新設するならConnectを先に検討してください。@connectrpc/connect-webは2.1.2が最新で、ConnectプロトコルとgRPC-Web互換の両方を同じクライアントから扱え、対応サーバならプロキシを1段減らせます。既存のgRPCサーバとEnvoy構成が動いていて、それを触らずにブラウザ経路だけ足すのであれば、gRPC-Webのままで追加投資は不要です。判断の軸は、バックエンドとインフラをどこまで変更できるかに置くのが実務的です。

関連記事

• gRPCとは？仕組み・RESTとの違い・UDP/TCPの扱いを実装例つきで解説：土台となるgRPC本体の仕組みとRESTとの違い
• Protocol Buffersとは？protoファイルの書き方と採用判断を実装者向けに解説：ブラウザ側の生成元になるスキーマの書き方
• Connect（connectrpc）とは？gRPC・RESTとの違いと使い方をわかりやすく解説：プロキシを減らせる代替プロトコル
• APIゲートウェイとは？役割・機能とリバースプロキシ／サービスメッシュとの違い・導入判断を解説：前段に置く部品の役割分担
• WebSocketとは？仕組み・ハンドシェイクからNode.js実装・運用の判断まで実装者向けに解説：連続送出が要る場合の選択肢