读取指定字节长度的二进制文件字符串时遇解码异常求助

问题概述 #

有一个结构明确的二进制文件：

• 字节0为文件版本号
• 剩余字节为记录，每个记录包含：
  • 2字节lane number（uint16）
  • 4字节tile number（uint32）
  • 2字节read number（uint16）
  • 2字节indexLength（索引名字节长度，uint16）
  • 对应长度的索引名字符串

读取表头及固定字段正常，但按indexLength读取索引名字节并以UTF-8解码时，出现读取字节远超预期、**UnicodeDecodeError（无法解码0xa9字节）**的问题。

代码片段 #

samples: list[dict] = [] # empty list to hold sample dicts

with open(path, "rb") as f:
    # get file version (first byte)
    version = struct.unpack("B", f.read(1))[0]
    logger.debug(f"IndexMetricsOut.bin file version: {version}")

    while True:
        # fixed fields chunking
        # lane (2), tile (4), read (2), indexLength(2)
        fixed_format = "HIHH"
        size = struct.calcsize(fixed_format)
        chunk = f.read(size)

        # if end of file
        if not chunk:
            logger.debug(f"End of file reached")
            break

        # assign fixed byte variables
        lane, tile, read_num, index_len = struct.unpack(fixed_format, chunk)
        logger.debug(f"lane: {lane}, tile: {tile}, "
                     f"read_num: {read_num}, index_len: {index_len}")
        
        def unpack_helper(fmt, data):
            size = struct.calcsize(fmt)
            return struct.unpack(fmt, data[:size]), data[size:]

        # decode and assign index_name based on index_len
        index_name_bytes = f.read(index_len)
        index_name = index_name_bytes.decode(encoding = "utf-8")

        print(index_name)

错误日志 #

tests.readindexbin::DEBUG: IndexMetricsOut.bin file version: 2
tests.readindexbin::DEBUG: lane: 1, tile: 65536, read_num: 21, index_len: 16705
b'CACTGTTA-TGAGACTTGC\x1ad\x06\x00\x00\x00\x00\x00\x1d\x00MMR_YPZ_PYI-1504_50898847_180\x07\x00default\x0 ...
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa9 in position 177: invalid start byte

核心问题与解决步骤 #

1. 字节序不匹配（根本原因） #

从日志看index_len = 16705明显异常——正常索引名长度不可能这么大，说明struct解包时使用的字节序与文件实际字节序不匹配。Python的struct模块默认使用本地字节序，但多数二进制文件（比如测序领域的Illumina文件）会使用固定字节序（小端或大端）。

解决方法：
在格式字符串前添加字节序标记：

• 小端字节序（常见）：修改为fixed_format = "<HIHH"
• 大端字节序：修改为fixed_format = ">HIHH"

调整后重新运行，检查index_len是否变为合理值（比如8、16这类索引名常见长度）。

2. 编码兼容处理 #

如果字节序修正后仍出现解码错误，可能是索引名并非UTF-8编码：

• 尝试使用latin-1编码（可兼容所有字节）：

  index_name = index_name_bytes.decode(encoding="latin-1")
  

• 或者保留无法解码的字节，避免程序崩溃：

  index_name = index_name_bytes.decode(encoding="utf-8", errors="replace")
  

3. 验证读取位置（可选） #

可以在每次读取后打印文件指针位置，确认是否按预期推进：

print(f"Current file position: {f.tell()}")

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