当前位置：首页 > news >正文

builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All))了解

news 2025/10/9 11:35:32

一句话作用

把 ASP.NET Core 默认的 HTML 转义器换成“不限制 Unicode 范围”的版本，
防止中文、emoji、西里尔字母等字符被强行转义成 &#xXXXX; 实体，
让网页源码更干净、体积更小。

逐段拆解

HtmlEncoder 是什么
- 位于 System.Text.Encodings.Web 命名空间；
- 负责把 < > & " 以及“被认为不安全”的字符转成 < > & &#xXXXX;；
- ASP.NET Core 在 Razor TagHelper、HtmlHelper、JsonSerializer 等内部都拿它做转义。
默认行为
框架启动时会自动注册一个“保守”的 HtmlEncoder，它只允许
BasicLatin（就是 ASCII 码 0-127）不加转义，
所有中文、emoji、带重音的拉丁字母统统转义成 中文 这种实体，
导致页面源码膨胀，可读性下降。
UnicodeRanges.All 做了什么
这个静态属性返回一个数组，里面包含所有已定义的 Unicode 区块（CJK、韩文、 emoji、数学符号……）。
把它喂给 HtmlEncoder.Create(...) 后，编码器会认为
“除了真正危及 HTML 语法的 < > & " 之外，其余字符一律原样输出”，
于是中文、日文、emoji 直接出现在 HTML，不再变成 &#x 实体。
注册到 DI 容器
AddSingleton<HtmlEncoder>(...) 用我们自己构造的实例
替换了框架默认注册的那个“只认 ASCII”的实例。
此后整个应用
- Razor 视图
- @Html.Encode / @Html.Raw
- TagHelper 输出
- System.Text.Json 写 HTML 片段
  都会使用这个“全开”的编码器。

完整代码片段

csharp

复制

using System.Text.Encodings.Web;
using System.Text.Unicode;var builder = WebApplication.CreateBuilder(args);// 1. 引入包（SDK 已自带，无需额外 NuGet）
// 2. 注册“不转义非 ASCII”的 HTML 编码器
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));// 3. 其他服务
builder.Services.AddControllersWithViews();var app = builder.Build();
...

效果对比

表格

场景	默认编码器	注册后
Razor 输出 `<p>你好 😄</p>`	`<p>你好 😄</p>`	`<p>你好 😄</p>`
页面大小	增加 2~3 倍	原样输出，体积最小
可读性	一堆 `&#x` 实体	源码即所见

注意事项

只影响 HTML 实体转义，不会关闭 XSS 保护；
< > & " 依旧会被转义，放心使用。
如果还要让 JavaScript 字符串也不转义非 ASCII，
可再配一句：
csharp
复制
```
builder.Services.AddSingleton(JavaScriptEncoder.Create(UnicodeRanges.All));
```
对 URL 编码无影响，URL 仍按 UTF-8 percent-encoding 规则。