.NET Core构建操作系统影响JSON输出编码问题排查

问题根源 #

这个问题核心在于构建环境编码不统一，以及ASP.NET Core默认JSON编码器的配置限制：

• Linux构建代理默认locale若不是UTF-8，编译时源文件中的特殊字符（如葡萄牙语的ç）会被错误解析，导致生成的程序集里的字符串本身已损坏。
• System.Text.Json默认编码器会对部分非ASCII字符进行转义，或未包含葡萄牙语所需的Unicode字符范围，最终输出异常字符。

解决方案 #

1. 强制项目文件使用UTF-8编码 #

在项目的.csproj文件中添加以下配置，确保编译时源文件以UTF-8格式解析：

<PropertyGroup>
  <!-- 强制源文件编码为UTF-8 -->
  <FileEncoding>UTF-8</FileEncoding>
  <LangVersion>latest</LangVersion>
</PropertyGroup>

2. 全局配置JSON编码器支持全Unicode范围 #

构建服务时，显式配置System.Text.Json编码器，确保能正确输出所有Unicode字符：

var builder = WebApplication.CreateBuilder(args);

// 配置JSON输出选项
builder.Services.Configure<Microsoft.AspNetCore.Http.Json.JsonOptions>(options =>
{
    // 允许输出所有Unicode字符，避免转义或丢失
    options.SerializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.Create(
        System.Text.Unicode.UnicodeRanges.All
    );
});

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// 后续代码保持不变...

若项目使用Controllers架构，配置方式调整为：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.Create(
            System.Text.Unicode.UnicodeRanges.All
        );
    });

3. 确保Azure DevOps Linux构建代理使用UTF-8 locale #

在Azure DevOps的YAML构建管道中，添加前置步骤设置环境编码，确保构建前locale生效：

steps:
  - script: |
      sudo locale-gen pt_PT.UTF-8
      export LC_ALL=pt_PT.UTF-8
      export LANG=pt_PT.UTF-8
    displayName: 'Set UTF-8 Locale for Build'
    # 此步骤必须在dotnet build之前执行

  - task: DotNetCoreCLI@2
    displayName: 'Build Project'
    inputs:
      command: 'build'
      projects: '**/*.csproj'

验证步骤 #

1. 提交修改后的项目文件和YAML配置到Azure DevOps
2. 触发Linux构建任务
3. 下载构建产物，在Windows或Ubuntu WSL中运行API，访问/weatherforecast端点验证字符是否正常显示

内容的提问来源于stack exchange，提问作者Diogo Mendonça