企业官网建设流程全解析

简介：使用C#开发的Blazor WebAssembly与gRPC端到端集成示例，面向希望掌握Blazor前端直连gRPC后端、追求客户端与服务器代码高度复用的.NET开发者。项目以.proto文件统一定义API契约，借助代码生成自动创建gRPC客户端与服务端，避免手工维护接口同步问题。压缩包共59个文件，以cs源码、razor组件、json配置、csproj工程文件为主，辅以dockerfile与yaml便于容器化部署，整体仅235KB，结构精炼，目前已有307人学习使用。通过该示例可直观理解如何搭建gRPC网关、构建一元调用服务端、编写Blazor客户端调用逻辑，并参考多项目分层与Docker编排方式，适合具备C#基础、希望将gRPC引入Web场景的中级开发者快速上手。

1. BlazorGrpc到底解决什么问题

BlazorGrpc 这个标题，说白了就是把 Blazor WebAssembly 和 gRPC 串在一起。Blazor WebAssembly 让 C# 代码直接跑在浏览器里，gRPC 又是目前服务间通信里效率最高的 RPC 协议之一，但浏览器不允许 WebAssembly 直接发起真正的 HTTP/2 二进制 gRPC 调用，中间必须用 gRPC-Web 做桥接。这个方向最典型的应用场景是：前后端都用 C#、想共享一份 ProtoBuf 契约、不想在通信层重复写 DTO 和序列化代码的团队。

适合谁？后端已经有 gRPC 服务想复用，或者新项目从第一天就想把接口契约单独管理的人。不适合谁？在做公共 API、需要给外部团队开放 HTTP 接口、或者希望用浏览器开发者工具直接看到可读 JSON 的场合，gRPC-Web 反而会增加理解成本。这篇文章按我自己的落地路径来讲：先是选型取舍，然后从空项目搭一个最小示例，再把超时、取消、流式这些参数讲清楚，最后给认证和验证技巧。

2. 为什么浏览器不能直接用 gRPC：HTTP/2 的锅与 gRPC-Web 选型

2.1 HTTP/2 trailer 在浏览器里被吞掉了

gRPC 的通信模型看起来简单：一条 POST 请求，路径是/包名.服务名/方法名，body 是 Protobuf 二进制，服务端结果也编码成二进制。但真正微妙的地方在元数据：gRPC 把 grpc-status、grpc-message 这类关键状态信息放在 HTTP/2 的 trailer 里，也就是响应体发完之后才跟着出来的那批头字段。

问题就在这里。浏览器的 fetch 和 XMLHttpRequest 只暴露响应头和响应体，HTTP/2 trailer 对 JavaScript 来说基本不可见。也就是说，Blazor WebAssembly 里发起一个真正的 gRPC 调用，服务端成功返回了，但客户端拿不到 grpc-status，拿不到 grpc-message，只看到一个裸的 EOF。这不是性能问题，是协议语义在浏览器这一端被阉割了。gRPC 团队也知道这一点，所以官方给出了 gRPC-Web 这套配套协议。

我一开始理解这个问题时绕了远路，以为是 HTTP/2 多路复用的原因导致浏览器不支持，后来抓包才发现，浏览器其实支持 HTTP/2，关键是它不把 trailer 暴露给上层。所以结论很直接：想在浏览器里用 gRPC，就一定得靠 gRPC-Web 做转换层，没有别的正规路径。

2.2 gRPC-Web 到底改了什么

gRPC-Web 协议不改变你的方法签名和 Protobuf 描述，它只改传输格式。ASP.NET Core 的Grpc.AspNetCore.Web中间件在服务端把普通 gRPC 响应重新封装成 gRPC-Web 帧：数据帧里放业务消息，末尾单独放一个 trailer 帧，里面装着 grpc-status、grpc-message 这些键值对。客户端这边，Grpc.Net.Client.Web包里的GrpcWebHandler负责反向拆帧，把 trailer 帧里的状态解析出来，重新包装成业务代码熟悉的RpcException。

请求方向也一样：客户端把 content-type 从application/grpc改成application/grpc-web+proto，如果是文本模式则用application/grpc-web-text做 base64 传输。x-grpc-web: 1头标记这是一个 gRPC-Web 请求。服务端中间件看到这个头，就知道该走 gRPC-Web 编码路径而不是普通 gRPC 路径。

提示：GrpcWebMode.GrpcWeb走二进制，GrpcWebMode.GrpcWebText走 base64。浏览器里默认用二进制模式即可，除非你的代理层对二进制 content-type 有干扰。

我的建议是：把这个转换层理解成一个透明的适配器，业务代码里你仍然写client.GetWeatherAsync(...)，底层从 Channel 到 Wire 的转换全都由GrpcWebHandler接管。你在 Blazor 里写的代码和纯服务端 gRPC 客户端几乎一模一样。

2.3 什么时候不该用 gRPC-Web

gRPC-Web 不是银弹。它最大的硬伤是流式能力不对称：gRPC-Web 协议规范只支持一元调用和服务器流式，客户端流式和双向流式在浏览器端没有对应实现。如果你需要高频双向推送，选 SignalR 更合理。

第二个不适合的场合是公共 API。外部团队不一定有 gRPC-Web 客户端，他们更习惯打开浏览器看 JSON。就算你在服务端保留普通 gRPC 端点，外部调用方也得能连上 HTTP/2，这在部分内网环境下并不容易。

第三个是调试体验。gRPC-Web 的请求体是二进制帧，浏览器 DevTools 里看不到可读内容，错误排查必须依赖服务端日志和客户端拦截器。团队里如果新人比例高，上来就上 gRPC-Web 的陡峭程度会比 REST 高不少。我现在的选择标准是：前后端同构、契约需要强类型共享、并发生物量大，满足这三点才值得上 gRPC-Web；否则老老实实用 REST 加 OpenAPI，省心。

3. 搭一个最小可跑的 BlazorGrpc 示例：从两个空项目到第一次调用

3.1 创建服务端与客户端项目骨架

示例我按最常见的部署形态来：两个项目，一个是 ASP.NET Core 服务端，承载 gRPC 服务和 gRPC-Web 中间件；一个是 Blazor WebAssembly 客户端，负责 UI 和调用。先建骨架：

dotnet new blazorwasm -n BlazorGrpc.Client -o src/BlazorGrpc.Client --empty dotnet new web -n BlazorGrpc.Server -o src/BlazorGrpc.Server cd src/BlazorGrpc.Server dotnet add package Grpc.AspNetCore dotnet add package Grpc.AspNetCore.Web cd ../BlazorGrpc.Client dotnet add package Grpc.Net.Client dotnet add package Grpc.Net.Client.Web dotnet add package Google.Protobuf dotnet add package Grpc.Tools

这里--empty能去掉默认模板里的跳棋页面和样板代码，让示例更纯粹。服务端加的两个包，Grpc.AspNetCore提供 gRPC 服务端运行时和 ProtoBuf 生成能力，Grpc.AspNetCore.Web提供 gRPC-Web 转换中间件。客户端这边，Grpc.Net.Client负责 Channel 和调用逻辑，Grpc.Net.Client.Web提供GrpcWebHandler，Google.Protobuf是消息基类，Grpc.Tools负责从.proto生成 C# 代码，不需要手动安装 protoc。

3.2 定义一份 Proto 契约，同时服务两个项目

在服务端建一个Protos/weather.proto，内容如下：

syntax = "proto3"; package weather; option csharp_namespace = "BlazorGrpc.Protos"; service WeatherForecasts { rpc GetWeather (WeatherRequest) returns (WeatherReply); rpc SubscribeWeather (WeatherRequest) returns (stream WeatherReply); } message WeatherRequest { string city = 1; } message WeatherReply { string city = 1; double temperature_c = 2; string summary = 3; int64 timestamp_unix = 4; }

逻辑说明：这个契约里定义了两个方法，GetWeather是一元调用，客户端发一个城市名，服务端返回一条天气记录；SubscribeWeather是服务器流式，客户端发请求后服务端持续推多条天气数据。csharp_namespace控制生成的 C# 命名空间，不写的话默认用 package 名。字段编号从 1 开始，是 Protobuf 二进制的硬性规则，编号一旦定下来后续不能随意变动。

接下来把同一份 proto 文件链接给客户端项目。在BlazorGrpc.Client.csproj中加入：

<ItemGroup> <Protobuf Include="..\BlazorGrpc.Server\Protos\weather.proto" Link="Protos\weather.proto" GrpcServices="Client" /> </ItemGroup>

服务端BlazorGrpc.Server.csproj中加：

<ItemGroup> <Protobuf Include="Protos\weather.proto" GrpcServices="Server" /> </ItemGroup>

关键参数是GrpcServices：写成Client只生成客户端代理类WeatherForecastsClient；写成Server只生成服务端抽象基类WeatherForecastsBase。如果你两边都写Both也没问题，但生成类型会多一倍，编译时间变长。我们按职责拆分，客户端项目里不会出现服务端基类，避免误用。

3.3 服务端启用 gRPC 与 gRPC-Web 桥接

服务端Program.cs完整配置如下：

using BlazorGrpc.Protos; var builder = WebApplication.CreateBuilder(args); builder.Services.AddGrpc(); builder.Services.AddCors(options => { options.AddPolicy("BlazorClient", policy => { policy.AllowAnyOrigin() .AllowAnyHeader() .AllowAnyMethod() .WithExposedHeaders("Grpc-Status", "Grpc-Message"); }); }); var app = builder.Build(); app.UseRouting(); app.UseGrpcWeb(); app.UseCors("BlazorClient"); app.MapGrpcService<WeatherService>().EnableGrpcWeb(); app.MapGet("/", () => "gRPC-Web server is running"); app.Run();

逻辑说明：AddGrpc()注册 gRPC 服务运行时；AddCors配置跨域策略，浏览器里发 gRPC-Web 请求必须过 CORS，否则请求在进入中间件之前就被拦截了。WithExposedHeaders("Grpc-Status", "Grpc-Message")让浏览器能读取到 gRPC 状态头，排查问题时从 DevTools 里能看到真实状态。UseGrpcWeb()必须在UseRouting()之后，UseEndpoints()之前，顺序错了转换不生效。每个 gRPC 服务端点要单独调.EnableGrpcWeb()，这个开关是端点级的，不是全局的，目的是让你能同时暴露原生 gRPC 端点和 gRPC-Web 端点。

服务实现类WeatherService.cs如下：

using BlazorGrpc.Protos; using Grpc.Core; public class WeatherService : WeatherForecasts.WeatherForecastsBase { public override Task<WeatherReply> GetWeather( WeatherRequest request, ServerCallContext context) { var reply = new WeatherReply { City = request.City, TemperatureC = 23.5, Summary = "多云", TimestampUnix = DateTimeOffset.UtcNow.ToUnixTimeSeconds() }; return Task.FromResult(reply); } public override async Task SubscribeWeather( WeatherRequest request, IServerStreamWriter<WeatherReply> responseStream, ServerCallContext context) { for (var i = 0; i < 5; i++) { await responseStream.WriteAsync(new WeatherReply { City = request.City, TemperatureC = 20 + i, Summary = $"第 {i + 1} 次采样", TimestampUnix = DateTimeOffset.UtcNow.ToUnixTimeSeconds() }); await Task.Delay(500, context.CancellationToken); } } }

逻辑说明：一元方法直接返回Task<WeatherReply>即可；流式方法靠IServerStreamWriter<T>持续写出多条消息。这里每 500 毫秒推一条，推 5 条后正常结束。context.CancellationToken是关键参数：客户端断开时这里会收到取消信号，循环里的Task.Delay必须传入这个 token，否则服务端会白跑完整个循环。

注意：MapGrpcService和EnableGrpcWeb这种写法只对 gRPC 服务生效。普通的 MVC Controller 端点没有EnableGrpcWeb方法，不要试图把 REST Controller 也套上去。

3.4 客户端 Channel 配置与第一次调用

客户端Program.cs里注册 Channel 和客户端代理：

using BlazorGrpc.Protos; using Grpc.Net.Client.Web; using Grpc.Net.Client; builder.Services.AddScoped(sp => { var baseAddress = builder.HostEnvironment.BaseAddress; var channel = GrpcChannel.ForAddress(baseAddress, new GrpcChannelOptions { HttpHandler = new GrpcWebHandler(GrpcWebMode.GrpcWeb, new HttpClientHandler()) }); return new WeatherForecasts.WeatherForecastsClient(channel); });

逻辑说明：builder.HostEnvironment.BaseAddress在独立部署时是客户端的部署地址，需要你在配置里换成 gRPC 服务端地址。我这里用相对地址的写法默认服务端和客户端部署在同域，实际项目里建议从appsettings.json读绝对地址。GrpcChannelOptions.HttpHandler是整个链路的精髓，不设置的话GrpcChannel走的是原生 HTTP/2 gRPC，在浏览器里直接崩；换成GrpcWebHandler后，客户端发出去的每一个请求都会被重新编码成 gRPC-Web 格式。GrpcWebMode.GrpcWeb选二进制模式，GrpcWebMode.GrpcWebText是 base64 文本模式，默认情况下用二进制就行。

页面里调用就很简单了：

@inject WeatherForecasts.WeatherForecastsClient WeatherClient @code { private string result = ""; private async Task FetchWeather() { var reply = await WeatherClient.GetWeatherAsync( new WeatherRequest { City = "滨海市" }); result = $"{reply.City}: {reply.TemperatureC}°C, {reply.Summary}"; } }

到这里，一个能跑通的最小 BlazorGrpc 示例就齐了。运行服务端后访问对应的端口，点击按钮就能看到服务端返回的数据。第一版出来了，接下来才是真正花时间的部分——把边界情况处理好。

4. 新手五连坑与排查：从 500 到 CORS

这一章是我自己反复翻车的记录。gRPC-Web 的坑不是藏在代码逻辑里，而是藏在协议语义和环境交互里，每条都是真实项目里踩过的，按“现象 → 原因 → 解决”写清楚。

4.1 错误全是 500 或网络错误，看不到真实状态码

现象：Blazor 页面上调用GetWeatherAsync，抛出RpcException或HttpRequestException，但 Details 里的内容和真正服务端错误对不上。看浏览器 DevTools，发现响应体是一片乱码，没有明确的 400 或 500。

原因：gRPC-Web 把 grpc-status 放在 trailer 帧里，浏览器 DevTools 不会自动解析这个帧。你看到的“网络错误”其实是浏览器认为响应头缺失导致的误报，服务端真实的业务异常被埋在了二进制帧里。

解决：一是看服务端日志，Microsoft.AspNetCore.Server.Kestrel或 gRPC 组件会打出真实异常堆栈。二是给客户端加拦截器，自己把StatusCode和Detail打到页面或控制台。三是用 curl 模拟 gRPC-Web 请求，手动查看返回头：

curl -i \ -H "Content-Type: application/grpc-web+proto" \ -H "X-Grpc-Web: 1" \ -X POST \ --data-binary @request.bin \ http://localhost:5000/weather.WeatherForecasts/GetWeather

request.bin是 Protobuf 编码的请求体，用protoc --encode生成。响应里如果能看到Grpc-Status: 0就说明链路通，非 0 值才是真正要排查的状态码。这条命令排查网络层问题非常快。

4.2 CORS 没配好，请求还没到 gRPC 就被拦截

现象：本地跑服务端和客户端都在 localhost，一切正常；部署到两个不同域名后，所有 gRPC 请求全部失败，浏览器 Console 报 CORS 错误。

原因：gRPC 请求和普通 REST 请求一样受同源策略限制，但比普通 REST 多几个坑：请求头里有content-type: application/grpc-web+proto、x-grpc-web，响应头里有grpc-status。默认的 CORS 策略如果不显式允许这些头，浏览器直接拒绝。AllowAnyHeader和AllowAnyMethod是必须的，另外记得WithExposedHeaders("Grpc-Status", "Grpc-Message")，否则浏览器 JS 连响应里的状态都读不到。

解决：服务端Program.cs里加 CORS 策略，并把UseCors放在UseGrpcWeb之前执行。我一般是app.UseRouting()后先UseCors，再UseGrpcWeb，这样跨域检查比协议转换先走，错误信息更清晰。

提示：AllowAnyOrigin不能和AllowCredentials同时启用。如果你打算在 Blazor WebAssembly 里带 Cookie 认证，就要用SetIsOriginAllowed加AllowCredentials，别图省事两个都开。

4.3 请求发出去了，服务端日志干干净净

现象：客户端点击按钮后，请求显示成功了，但服务端完全没有日志输出，也没有断点命中。你以为服务端没收到请求，其实收到了，但中间件把它当无效请求丢弃了。

原因：这是UseGrpcWeb和EnableGrpcWeb同时缺失时的经典表现。UseGrpcWeb()注册中间件，MapGrpcService<...>().EnableGrpcWeb()给端点开白名单。两个都缺，gRPC-Web 请求请求进入到 Kestrel 层，路由层匹配不上 endpoint，直接 404 或者被静默丢弃。

解决：检查两点。第一，app.UseGrpcWeb()是否在UseRouting之后、MapGrpcService之前；第二，MapGrpcService后面是否链了.EnableGrpcWeb()。还有一个隐藏点：如果你在 try 块里接住了所有异常，务必把RpcException重新抛出去，否则服务端日志不会出现任何痕迹，排查效率极低。

4.4 手动跑 protoc 生成的代码和 NuGet 包版本对不上

现象：项目编译通过，但在运行时抛MissingMethodException，或者序列化的字段解析出来全是默认值。这种错误出现得毫无规律，重启后可能又好了。

原因：有人为了绕过Grpc.Tools，手动从网上下载了 protoc 可执行文件来生成代码。protoc 生成的代码版本和Google.ProtobufNuGet 包版本不一致时，运行时会调用不存在的方法，或者字段编号偏差导致解析错位。这是典型的环境玄学，浪费了我大半天时间。

解决：不要手动跑 protoc，项目里Grpc.Tools包就是官方指定的代码生成器，它会自动下载匹配版本的 protoc 插件。删掉所有手动生成的.cs文件，只保留.proto源文件，让 MSBuild 的ProtobufItemGroup 接管生成。另外注意，Grpc.Tools、Google.Protobuf、Grpc.Net.Client三个包的版本尽量保持同一次 NuGet 还原，别混着升级。

4.5 服务地址写死，换环境必然 404

现象：本地跑得好好的，发布到测试服务器后，所有 gRPC 调用都报连接失败或 404。检查防火墙没问题，服务端也启动了，但就是连不上。

原因：客户端代码里把服务端地址写成了"https://localhost:5001"，发布到测试环境后仍然指向开发机，当然连不上。还有一种情况是用了builder.HostEnvironment.BaseAddress，但客户端和服务端部署在同一个服务器的不同路径下，相对地址拼出来是错的。

解决：服务端地址绝对不要写死在代码里，放到appsettings.json里绑定字符串：

{ "GrpcServerUrl": "https://server.example.com" }

客户端注入时读取配置。如果没有配置管理工具，至少也要放到一个静态常量类里并加上注释，让接手的开发者一眼能意识到这个值要按环境替换。这类问题属于“部署五分钟，排查两小时”的典型，花在配置规范化上的时间是绝对值得的。

5. 把示例调成能上线的参数：超时、取消、流式与链路验证

5.1 超时与取消：CallOptions 里必须显式传的两样东西

不传 deadline 的 gRPC 调用，默认可以无限等下去。浏览器环境下，这个状态特别容易拖垮页面。我的习惯是每次调用都显式设置两个参数：deadline 和 cancellation token。

using Grpc.Core; var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10)); var options = new CallOptions( headers: new Metadata { { "x-request-id", Guid.NewGuid().ToString() } }, deadline: DateTime.UtcNow.AddSeconds(5), cancellationToken: cts.Token); WeatherReply reply; try { reply = await WeatherClient.GetWeatherAsync( new WeatherRequest { City = "滨海市" }, options); } catch (RpcException ex) when (ex.StatusCode == StatusCode.DeadlineExceeded) { // 提示用户服务超时，不把异常抛到 UI 层 }

参数说明：deadline是绝对时间，服务端收到后会与本地时钟做对比，超过即中止请求；cancellationToken是客户端本地取消信号。两者同时设置时，以先触发的那个为准。Blazor 组件销毁时记得把cts.Cancel()调一下，否则组件已经被路由切走，响应回来时更新 UI 就会抛ObjectDisposedException。标准做法是在OnDisposeAsync里取消：

protected override void OnDisposeAsync() { _cts?.Cancel(); _cts?.Dispose(); return base.OnDisposeAsync(); }

这里容易忽略的一点：gRPC-Web 的取消不是即时生效的。浏览器端的取消只是让客户端停止等待，服务端收到取消信号可能需要等连接关闭后才触发。所以服务端别把context.CancellationToken当成严格的事务回滚依据，它只是一个尽力而为的协作信号。

5.2 流式支持的限制：一元和服务器流式才稳

gRPC-Web 协议规范只定义了两种模式：Unary 和 Server Streaming。客户端流式和双向流式在浏览器端没有标准实现，ASP.NET Core 的 gRPC-Web 中间件会直接对这两种调用返回 UNIMPLEMENTED 状态。如果你想做聊天或实时协同，用 SignalR 别用 gRPC-Web。

服务器流式在 Blazor 里可以这么接：

using var call = WeatherClient.SubscribeWeather( new WeatherRequest { City = "滨海市" }); try { await foreach (var item in call.ResponseStream.ReadAllAsync()) { items.Add(item); await InvokeAsync(StateHasChanged); } } catch (OperationCanceledException) { // 组件销毁或用户主动取消时正常退出 }

逻辑说明：ReadAllAsync()返回IAsyncEnumerable<WeatherReply>，Blazor WebAssembly 里直接await foreach即可。服务端每推一条消息，这里就迭代一次，然后用InvokeAsync(StateHasChanged)刷新 UI。using var call保证流结束时释放连接。要点是catch里一定接住OperationCanceledException，因为取消是流式调用的常态结束方式，不接住会直接抛到组件外导致页面错误。

5.3 链路验证：拦截器加服务端日志，五分钟定位问题

gRPC-Web 的调试难点在于看不到请求内容，所以一定要在客户端加拦截器。以下是一个统计耗时的拦截器实现：

using Grpc.Core; using Grpc.Core.Interceptors; public class TimingInterceptor : Interceptor { public override AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>( TRequest request, ClientInterceptorContext<TRequest, TResponse> context, AsyncUnaryCallContinuation<TRequest, TResponse> continuation) { var stopwatch = System.Diagnostics.Stopwatch.StartNew(); var call = continuation(request, context); var responseTask = Continuate(call.ResponseAsync, stopwatch); return new AsyncUnaryCall<TResponse>( responseTask, call.ResponseHeadersAsync, call.GetStatus, call.GetTrailers, call.Dispose); } private static async Task<TResponse> Continuate<TResponse>( Task<TResponse> task, System.Diagnostics.Stopwatch sw) { var result = await task; sw.Stop(); Console.WriteLine($"gRPC 调用耗时: {sw.ElapsedMilliseconds} ms"); return result; } }

逻辑说明：拦截器在调用发起前启动计时，响应回来后打印耗时。这个信息在开发环境特别有用，能立刻判断问题是序列化开销还是网络延迟。注册方式是在客户端注册代码里手动包一层：

var inner = new WeatherForecasts.WeatherForecastsClient(channel); return new WeatherForecasts.WeatherForecastsClient( new TimingInterceptor().Intercept(inner));

服务端日志的配置同样重要。在appsettings.json里把 gRPC 相关日志级别调到 Information：

{ "Logging": { "LogLevel": { "Default": "Information", "Grpc": "Information" } } }

调高日志级别后，每个 gRPC 请求的进入、完成、异常都会被打印，排查问题时一眼就能看到方法名、耗时和状态码。我排查 gRPC-Web 问题从来只依赖两样东西：客户端拦截器打印的耗时，服务端日志打出的异常堆栈。这两个比任何抓包工具都直接。

6. 进阶技巧：统一认证头与一次性能打点

6.1 用 DelegatingHandler 统一加认证头

既然用 gRPC-Web，请求最终会变成 HTTP 请求，那我加认证头就不需要在每个方法调用里手动塞 Metadata。定义一个继承DelegatingHandler的认证处理器：

public class AuthHandler : DelegatingHandler { private readonly TokenProvider _tokenProvider; public AuthHandler(TokenProvider tokenProvider) { _tokenProvider = tokenProvider; } protected override async Task<HttpResponseMessage> SendAsync( HttpRequestMessage request, CancellationToken cancellationToken) { var token = await _tokenProvider.GetTokenAsync(); request.Headers.TryAddWithoutValidation( "Authorization", $"Bearer {token}"); return await base.SendAsync(request, cancellationToken); } }

注册时把认证处理器放在GrpcWebHandler外层，请求先加认证头，再进行 gRPC-Web 编码：

var authHandler = new AuthHandler(tokenProvider) { InnerHandler = new GrpcWebHandler( GrpcWebMode.GrpcWeb, new HttpClientHandler()) }; var channel = GrpcChannel.ForAddress(baseAddress, new GrpcChannelOptions { HttpHandler = authHandler });

这样业务代码里完全不用碰 Metadata，认证逻辑收口在管道两端。Token 失效时在TokenProvider.GetTokenAsync里统一刷新即可，不用改调用方。

6.2 十分钟做一次性能打点：gRPC-Web 到底值不值

我建议你在选型阶段就做一次简单的量化对比，而不是凭感觉。用同一个服务，分别提供 gRPC-Web 和 REST JSON 两个端点，各打一次分，对比四个指标：

打点方式很简单，用浏览器 Performance API 记录 fetch 时间，或者用服务端日志统计平均耗时。我实测过同一个数据对象，JSON 序列化后约 400 字节，Protobuf 约 120 字节，传输时间的差异在网络条件好的内网里几乎感觉不到，但在弱网环境下体感差距明显。这就是为什么我说 gRPC-Web 适合并发和弱网场景，不适合日常后台管理系统。

最后提一个我的习惯：gRPC-Web 的坑大多不是代码逻辑的问题，而是部署、CORS、版本这三座大山。每次换环境都要检查一遍 gRPC 服务端地址、CORS 策略和包版本，把它们当成发布清单的一部分。双向流这种功能在浏览器里能用就别指望，老老实实用顺势而为的方案。希望帮到你。

本文还有配套的精品资源，点击获取