.NET Core跨平台UTF8编码不一致问题排查与解决方案咨询

问题背景 #

我有一个.NET Core 2 xUnit测试项目，专门验证字符串"é"的UTF-8编码和解码逻辑。奇怪的是，这些测试在Windows平台的Appveyor上全部通过，但到了Linux和macOS的Travis环境就直接失败了。测试代码如下：

[Fact]
public void CanEncode()
{
    var character = "é";
    var encoded = Encoding.UTF8.GetBytes(character);
    var bytes = new byte[] { 195, 169 };
    Assert.Equal(bytes, encoded);
}
[Fact]
public void CanDecode()
{
    var character = "é";
    var bytes = new byte[] { 195, 169 };
    var decoded = Encoding.UTF8.GetString(bytes);
    Assert.Equal(character, decoded);
}
[Fact]
public void CanEncodeDecode()
{
    var character = "é";
    var encoded = Encoding.UTF8.GetBytes(character);
    var decoded = Encoding.UTF8.GetString(encoded);
    Assert.Equal(character, decoded);
}

Travis Linux环境下的测试失败核心表现：编码后的字节数组和预期的{195,169}不匹配，解码后的字符串也和原字符串不一致。

问题根源 #

这个跨平台不一致的问题，本质是源代码文件的编码格式在不同平台被解析的方式不同：

• 在Windows环境中，很多编辑器默认用Windows-1252（或GBK等本地编码）保存文件，字符串字面量"é"会被存储为单个字节0xE9，.NET编译器按Windows默认编码解析后能得到正确的"é"。
• 但到了Linux和macOS环境，.NET编译器默认以UTF-8编码读取源代码。如果源代码是Windows-1252编码，0xE9这个字节在UTF-8中是无效单字节序列，编译器会将其替换为替换字符�（U+FFFD），后续测试自然失败。
• 还有一种少见情况：若源代码是UTF-8带BOM（字节顺序标记）保存，Windows编译器可正确识别，但Linux/macOS编译器可能把BOM当成字符串的一部分，也会导致测试失败。

解决方法 #

要保证跨平台一致性，可以从以下几个方面入手：

1. 强制源代码文件以UTF-8无BOM编码保存

这是基础解决方式，确保所有平台的编译器读取源代码时用同一种编码：

• Visual Studio：点击「文件」→「高级保存选项」，选择「UTF-8 无签名」保存文件。
• VS Code：点击右下角的编码显示（如「GBK」），选择「通过编码保存」→「UTF-8」。
• 其他主流编辑器（如JetBrains Rider）都有类似设置，直接将默认编码设为UTF-8即可。

2. 使用Unicode转义序列代替直接写特殊字符

这是最稳妥的方式，彻底规避源代码编码依赖。"é"对应的Unicode码点是U+00E9，可写成"\u00E9"，修改后的测试代码如下：

[Fact]
public void CanEncode()
{
    var character = "\u00E9"; // 用Unicode转义序列代替"é"
    var encoded = Encoding.UTF8.GetBytes(character);
    var bytes = new byte[] { 195, 169 };
    Assert.Equal(bytes, encoded);
}

[Fact]
public void CanDecode()
{
    var character = "\u00E9";
    var bytes = new byte[] { 195, 169 };
    var decoded = Encoding.UTF8.GetString(bytes);
    Assert.Equal(character, decoded);
}

[Fact]
public void CanEncodeDecode()
{
    var character = "\u00E9";
    var encoded = Encoding.UTF8.GetBytes(character);
    var decoded = Encoding.UTF8.GetString(encoded);
    Assert.Equal(character, decoded);
}

这种方式下，无论在哪个平台编译，字符串内容都是确定的U+00E9字符，测试结果自然一致。

3. 在项目文件中显式指定编译器编码

在.csproj文件中添加配置，强制.NET编译器使用UTF-8编码读取源代码：

<PropertyGroup>
  <CodePage>65001</CodePage> <!-- 65001是UTF-8的代码页编号 -->
</PropertyGroup>

该配置会告诉编译器，无论当前系统默认编码是什么，都用UTF-8解析源代码文件。

总结 #

以上三种方法都能解决跨平台测试不一致的问题：使用Unicode转义序列是最彻底的方式，完全避免编码依赖；设置源代码编码和项目配置则是从环境层面保证一致性。

内容的提问来源于stack exchange，提问作者nopara73