PlatformIO生成HEX文件全攻略：从STM32到51单片机的实战避坑指南

PlatformIO生成HEX文件全攻略：从STM32到51单片机的实战避坑指南

如果你是从Keil或IAR这类传统IDE转向PlatformIO的开发者，可能会发现一个看似简单却让人困惑的问题：为什么PlatformIO默认不生成HEX文件？在Keil里，生成HEX文件只需要在Output选项卡里勾选一个复选框，但在PlatformIO里，这个看似基础的功能却需要额外的配置。这背后其实反映了两种开发哲学的根本差异——Keil等传统IDE倾向于提供开箱即用的完整解决方案，而PlatformIO则更注重灵活性和可定制性，将控制权交还给开发者。

对于许多嵌入式开发者来说，HEX文件仍然是不可或缺的。无论是使用STC-ISP烧录51单片机，还是通过某些串口工具烧录STM32，HEX格式因其包含地址信息和校验和而备受青睐。我在实际项目中就遇到过这样的情况：客户的生产线使用特定的烧录工具，只支持HEX格式，而我们的开发环境已经全面转向PlatformIO。这迫使我深入研究了PlatformIO的构建系统，最终找到了一套既优雅又实用的解决方案。

本文将带你深入PlatformIO的构建机制，不仅教你如何在STM32和51单片机项目中生成HEX文件，更重要的是，我会分享在实际开发中遇到的各种“坑”以及如何避开它们。无论你是刚接触PlatformIO的新手，还是已经使用了一段时间但遇到奇怪问题的开发者，这篇文章都能为你提供实用的指导。

1. PlatformIO构建系统深度解析

要理解为什么PlatformIO默认不生成HEX文件，我们首先需要了解它的构建流程。PlatformIO本质上是一个构建系统管理器，它基于Python的SCons构建工具，通过platformio.ini配置文件来定义整个项目的构建、上传和调试过程。

1.1 默认输出格式的选择逻辑

PlatformIO默认生成两种文件：.elf和.bin。.elf文件包含完整的调试信息、符号表和可重定位代码，主要用于调试；.bin文件则是纯粹的二进制镜像，可以直接烧录到Flash的起始地址。这种设计选择有其合理性：

• 调试优先：.elf文件配合GDB可以实现在线调试，这是现代开发流程中的重要环节
• 最小化输出：.bin文件体积最小，适合OTA升级和批量生产
• 灵活性：开发者可以根据需要自定义额外的输出格式

然而，这种“合理”的设计在实际工作中可能带来不便。我最近的一个项目就遇到了问题：硬件团队使用的烧录器只支持HEX格式，而我们的CI/CD流水线基于PlatformIO。每次测试都需要手动转换格式，效率低下且容易出错。

1.2 构建后动作（Post-Action）机制

PlatformIO提供了一个强大的扩展机制：构建后动作。这允许开发者在编译完成后执行自定义的Python脚本。生成HEX文件正是利用了这个机制。让我们看看这个机制是如何工作的：

# 这是一个简化的构建流程示意图
构建流程 = {
    "预处理": ["头文件展开", "宏替换"],
    "编译": ["源代码 -> 汇编代码"],
    "汇编": ["汇编代码 -> 目标文件"],
    "链接": ["目标文件 -> ELF文件"],
    "后处理": ["ELF -> BIN", "ELF -> HEX（可选）"]
}

关键点在于，PlatformIO将.bin生成视为核心功能，而.hex生成则被设计为可选的扩展功能。这种设计哲学在开源工具中很常见：核心保持简洁，功能通过插件或脚本扩展。

1.3 不同平台的工具链差异

PlatformIO支持多种架构的微控制器，每种架构使用不同的工具链。生成HEX文件的方法也因此有所不同：

平台	编译器	工具链	HEX生成工具
STM32 (ARM Cortex-M)	arm-none-eabi-gcc	GNU Arm Embedded	arm-none-eabi-objcopy
51单片机 (8051)	sdcc	SDCC	sdobjcopy 或自定义脚本
AVR (Arduino)	avr-gcc	GNU AVR	avr-objcopy
ESP32 (Xtensa)	xtensa-esp32-elf-gcc	ESP-IDF	esptool.py

这种差异意味着我们不能指望一个通用的解决方案适用于所有平台。在实际配置时，必须考虑目标平台的特殊性。我在配置51单片机项目时就踩过坑：SDCC工具链的objcopy参数与GCC的有所不同，直接套用STM32的脚本会导致失败。

2. STM32平台HEX文件生成实战

对于STM32开发者来说，PlatformIO提供了相对完善的支持。但即便如此，生成HEX文件仍然需要一些配置。下面我将分享几种不同的方法，从最简单到最灵活，你可以根据项目需求选择合适的方式。

2.1 基础配置方法

最常用的方法是在项目根目录创建extra_script.py文件，然后在platformio.ini中引用它。但这里有一个细节很多人会忽略：脚本的放置位置和命名约定。

# extra_script.py - 标准HEX生成脚本
Import("env")

# 使用AddPostAction添加构建后动作
env.AddPostAction(
    "$BUILD_DIR/${PROGNAME}.elf",  # 触发动作的文件
    env.VerboseAction(" ".join([
        "$OBJCOPY", "-O", "ihex", "-R", ".eeprom",
        "$BUILD_DIR/${PROGNAME}.elf", 
        "$BUILD_DIR/${PROGNAME}.hex"
    ]), "Building $BUILD_DIR/${PROGNAME}.hex")
)

在platformio.ini中添加引用：

[env:genericSTM32F103C8]
platform = ststm32
board = genericSTM32F103C8
framework = arduino
extra_scripts = extra_script.py

这个方法看似简单，但我遇到过几个常见问题：

1. 路径问题：如果脚本不在项目根目录，需要使用相对路径或绝对路径
2. 变量展开：$BUILD_DIR和${PROGNAME}是PlatformIO的环境变量，确保它们正确展开
3. 权限问题：在Linux/macOS上，确保脚本有执行权限

2.2 多环境配置技巧

在实际项目中，我们经常需要为不同的开发板或配置创建多个环境。PlatformIO支持在同一个platformio.ini中定义多个环境，每个环境可以有自己的HEX生成配置。

; 公共配置
[env]
platform = ststm32
framework = stm32cube
monitor_speed = 115200
extra_scripts = pre:common_scripts.py

; 开发板A配置
[env:board_a]
board = genericSTM32F103C8
build_flags = -DBOARD_A
upload_protocol = serial

; 开发板B配置（带ST-Link调试器）
[env:board_b]
board = genericSTM32F407VET6
upload_protocol = stlink
debug_tool = stlink
build_flags = -DBOARD_B -DDEBUG_ENABLED

对于这种多环境配置，我建议将HEX生成脚本放在公共脚本中，或者为每个环境单独配置。我曾经在一个项目中使用共享脚本，结果发现不同环境需要的objcopy参数略有不同，导致其中一个环境的HEX文件无法正常烧录。

2.3 高级技巧：条件生成与自定义路径

有时候，我们可能只想在特定条件下生成HEX文件，比如只在发布版本中生成，或者将HEX文件输出到特定目录。这可以通过更复杂的Python脚本实现：

# advanced_hex_script.py
Import("env")

def after_build(source, target, env):
    # 检查是否应该生成HEX
    build_type = env.GetProjectOption("build_type", "debug")
    
    if build_type.lower() == "release":
        # 构建输出路径
        elf_path = target[0].get_abspath()
        hex_path = elf_path.replace(".elf", ".hex")
        
        # 执行objcopy命令
        objcopy = env.subst("$OBJCOPY")
        cmd = f'{objcopy} -O ihex -R .eeprom "{elf_path}" "{hex_path}"'
        
        print(f"生成HEX文件: {hex_path}")
        env.Execute(cmd)
        
        # 可选：复制到指定目录
        import shutil
        output_dir = "dist/hex_files"
        import os
        os.makedirs(output_dir, exist_ok=True)
        shutil.copy2(hex_path, output_dir)

# 注册构建后钩子
env.AddPostAction("$BUILD_DIR/${PROGNAME}.elf", after_build)

这个脚本展示了几个高级技巧：

• 根据构建类型决定是否生成HEX
• 使用env.subst()正确处理变量替换
• 将生成的HEX文件复制到自定义目录

2.4 常见问题与解决方案

在STM32平台上使用PlatformIO生成HEX文件时，我遇到过一些典型问题：

问题1：HEX文件生成但无法烧录

症状：HEX文件正常生成，但使用烧录工具时提示格式错误或校验失败。

解决方案： 检查objcopy的参数是否正确。对于STM32，正确的参数是-O ihex（Intel HEX格式）。有时候工具链更新会导致参数变化，可以通过命令行手动测试：

# 查看objcopy支持的格式
arm-none-eabi-objcopy --help | grep -i "output format"

# 手动测试转换
arm-none-eabi-objcopy -O ihex -R .eeprom firmware.elf firmware.hex

问题2：HEX文件比BIN文件大很多

症状：同样的程序，HEX文件体积可能是BIN文件的2-3倍。

原因分析： 这是正常现象。HEX文件是ASCII文本格式，包含地址记录、数据记录和校验和。而BIN文件是纯二进制数据。HEX文件的可读性和完整性校验是以体积为代价的。

问题3：多段内存的HEX文件生成

需求：有些STM32芯片有多个Flash扇区或包含EEPROM，需要生成包含多段数据的HEX文件。

解决方案： 使用objcopy的-j参数指定需要包含的段：

env.AddPostAction(
    "$BUILD_DIR/${PROGNAME}.elf",
    env.VerboseAction(" ".join([
        "$OBJCOPY",
        "-O", "ihex",
        "-j", ".text", "-j", ".data", "-j", ".rodata",
        "$BUILD_DIR/${PROGNAME}.elf",
        "$BUILD_DIR/${PROGNAME}.hex"
    ]), "Building HEX with specific sections")
)

3. 51单片机平台的特殊挑战与解决方案

51单片机（特别是STC系列）在PlatformIO上的支持相对较新，配置过程比STM32复杂得多。我花了相当长时间才让整个工具链稳定工作，期间遇到了各种意想不到的问题。

3.1 平台选择与配置

PlatformIO为51单片机提供了intel_mcs51平台，但默认配置可能不适用于所有芯片，特别是国产的STC系列。

; 基本的STC89C51配置
[env:STC89C51RC]
platform = intel_mcs51
board = STC89C51RC
framework = 
build_flags = -D F_CPU=11059200

这里有几个关键点需要注意：

1. board参数：必须与.platformio/platforms/intel_mcs51/boards/目录下的JSON文件匹配
2. framework：51单片机通常不使用框架，留空即可
3. F_CPU：必须与芯片实际晶振频率一致，否则延时函数不准

我遇到的一个典型问题是：某些STC芯片在boards目录中没有对应的定义。这时需要手动创建或修改JSON文件。例如，对于STC89C516RD+芯片：

// STC89C516RD.json
{
  "build": {
    "mcu": "stc89c516rd",
    "f_cpu": "11059200L"
  },
  "debug": {
    "tool": "custom"
  },
  "frameworks": [],
  "name": "Generic STC89C516RD",
  "upload": {
    "maximum_ram_size": 1280,
    "maximum_size": 65536,
    "protocol": "stcgal",
    "require_upload_port": true
  },
  "url": "http://www.stcmcu.com/",
  "vendor": "STC"
}

3.2 SDCC编译器配置

51单片机使用SDCC（Small Device C Compiler）作为编译器，这与ARM的GCC工具链有很大不同。

[env:STC89C516RD]
platform = intel_mcs51
board = STC89C516RD
compiler_path = C:/Program Files/SDCC/bin/sdcc.exe
build_flags = 
    -D F_CPU=11059200
    --model-large
    --xram-size 256
    --stack-auto

SDCC的编译选项需要特别注意：

• --model-large：指定内存模型
• --xram-size：外部RAM大小
• --stack-auto：自动堆栈管理

我在配置时遇到的最大问题是：PlatformIO有时会使用自带的SDCC，有时会使用系统安装的SDCC，导致编译结果不一致。解决方案是指定明确的compiler_path。

3.3 HEX文件生成的特殊处理

对于51单片机，生成HEX文件的方法与STM32不同。SDCC编译后默认生成.ihx文件，这是Intel HEX的一种变体。我们需要将其转换为标准的HEX文件。

# stc_hex_script.py
Import("env")
import os

def after_build(source, target, env):
    # SDCC默认生成.ihx文件
    build_dir = env.subst("$BUILD_DIR")
    ihx_path = os.path.join(build_dir, "firmware.ihx")
    hex_path = os.path.join(build_dir, "firmware.hex")
    
    # 使用packihx工具转换
    packihx = env.subst("$PACKIHX")
    if not packihx:
        # 尝试查找packihx
        import shutil
        packihx = shutil.which("packihx")
    
    if packihx and os.path.exists(ihx_path):
        cmd = f'"{packihx}" "{ihx_path}" > "{hex_path}"'
        env.Execute(cmd)
        print(f"已生成HEX文件: {hex_path}")
    else:
        print("警告: 无法找到packihx工具，HEX文件生成失败")

env.AddPostAction("$BUILD_DIR/firmware.ihx", after_build)

这个脚本的关键点：

1. SDCC输出的是.ihx文件，不是.elf
2. 需要使用packihx工具进行转换
3. 转换后的HEX文件可能还需要进一步处理才能被STC-ISP识别

3.4 烧录配置与问题排查

STC单片机的烧录是一大挑战。PlatformIO使用stcgal作为烧录工具，但配置不当会导致各种问题。

[env:STC89C516RD]
platform = intel_mcs51
board = STC89C516RD
upload_protocol = custom
upload_port = COM5
upload_speed = 2400
upload_flags = -P stc89
upload_command = stcgal -P stc89 -p $UPLOAD_PORT -b $UPLOAD_SPEED $SOURCE

常见问题及解决方案：

问题1：烧录时卡在"Waiting for MCU"

这是STC单片机烧录的典型问题，需要冷启动。

解决方案：

• 确保upload_speed设置为2400或更低
• 在提示"Waiting for MCU"时，断开并重新连接电源
• 某些芯片需要特定的启动时序

问题2：协议错误

错误信息：invalid choice: ' stc89'

解决方案： 注意-P参数后的空格！YAML/INI文件对空格敏感：

# 错误：有空格
upload_flags = -P stc89

# 正确：无空格
upload_flags = -P stc89

问题3：HEX文件格式不被识别

STC-ISP工具提示"文件格式错误"

解决方案： STC-ISP对HEX文件格式有特定要求。可以尝试以下方法：

1. 使用最新版本的stcgal
2. 在转换后手动编辑HEX文件，确保首行是:020000040000FA
3. 使用STC-ISP软件自带的格式转换功能

3.5 代码兼容性问题

从Keil迁移到PlatformIO时，代码本身可能需要修改。SDCC与Keil的C51编译器不完全兼容。

寄存器定义差异：

// Keil风格
sfr P0 = 0x80;
sbit LED = P0^0;

// SDCC风格
__sfr __at (0x80) P0;
__bit __at (0x80) LED;  // 注意：位地址计算方式不同

中断函数定义：

// Keil风格
void timer0_isr() interrupt 1 {
    // 中断处理
}

// SDCC风格
void timer0_isr() __interrupt(1) {
    // 中断处理
}

我建议为SDCC创建专用的头文件，或者使用条件编译：

// stc89.h
#ifdef __SDCC__
    // SDCC专用定义
    __sfr __at (0x80) P0;
    #define INTERRUPT(n) __interrupt(n)
#else
    // Keil专用定义
    sfr P0 = 0x80;
    #define INTERRUPT(n) interrupt n
#endif

4. 跨平台通用解决方案与最佳实践

经过多个项目的实践，我总结出了一套在PlatformIO中管理HEX文件的通用方案。这套方案不仅适用于STM32和51单片机，也可以扩展到其他平台。

4.1 模块化的脚本架构

我建议将构建脚本组织成模块化的结构，便于复用和维护：

项目根目录/
├── scripts/
│   ├── __init__.py
│   ├── hex_generator.py    # HEX生成核心逻辑
│   ├── stm32_hex.py        # STM32专用配置
│   ├── mcs51_hex.py        # 51单片机专用配置
│   └── utils.py            # 工具函数
├── platformio.ini
└── src/

hex_generator.py的核心逻辑：

# scripts/hex_generator.py
import os
from SCons.Script import Import

def setup_hex_generation(env, platform_specific_config=None):
    """设置HEX文件生成"""
    
    # 默认配置
    config = {
        'enabled': True,
        'output_dir': None,
        'additional_flags': '',
        'post_process': None
    }
    
    # 合并平台特定配置
    if platform_specific_config:
        config.update(platform_specific_config)
    
    if not config['enabled']:
        return
    
    # 确定输出路径
    if config['output_dir']:
        hex_path = os.path.join(config['output_dir'], "${PROGNAME}.hex")
    else:
        hex_path = "$BUILD_DIR/${PROGNAME}.hex"
    
    # 构建命令
    cmd_parts = ["$OBJCOPY", "-O", "ihex"]
    
    if config['additional_flags']:
        cmd_parts.extend(config['additional_flags'].split())
    
    cmd_parts.extend([
        "$BUILD_DIR/${PROGNAME}.elf",
        hex_path
    ])
    
    # 添加构建后动作
    env.AddPostAction(
        "$BUILD_DIR/${PROGNAME}.elf",
        env.VerboseAction(" ".join(cmd_parts), 
                         f"Building {hex_path}")
    )
    
    # 执行后处理函数
    if config['post_process'] and callable(config['post_process']):
        env.AddPostAction(hex_path, config['post_process'])

4.2 自动化测试与验证

生成HEX文件后，最好能自动验证其有效性。我创建了一个简单的验证脚本：

# scripts/verify_hex.py
import re
import os

def verify_hex_file(filepath):
    """验证HEX文件的完整性"""
    
    if not os.path.exists(filepath):
        return False, f"文件不存在: {filepath}"
    
    with open(filepath, 'r') as f:
        lines = f.readlines()
    
    if not lines:
        return False, "文件为空"
    
    # 检查HEX文件格式
    hex_pattern = re.compile(r'^:[0-9A-F]{2}[0-9A-F]{4}[0-9A-F]*[0-9A-F]{2}$')
    
    for i, line in enumerate(lines, 1):
        line = line.strip()
        
        # 忽略空行
        if not line:
            continue
            
        # 检查格式
        if not hex_pattern.match(line):
            return False, f"第{i}行格式错误: {line}"
        
        # 计算校验和
        if not verify_checksum(line):
            return False, f"第{i}行校验和错误: {line}"
    
    # 检查结束记录
    if not lines[-1].strip().startswith(':00000001FF'):
        return False, "缺少正确的结束记录"
    
    return True, "HEX文件验证通过"

def verify_checksum(hex_line):
    """验证HEX行的校验和"""
    # 移除起始的冒号
    data = hex_line[1:]
    
    # 计算校验和
    byte_count = int(data[0:2], 16)
    calculated_sum = byte_count
    
    # 累加所有字节
    for i in range(0, len(data)-2, 2):
        byte_val = int(data[i:i+2], 16)
        calculated_sum += byte_val
    
    # 取补码
    calculated_sum = (~calculated_sum + 1) & 0xFF
    
    # 获取文件中的校验和
    file_checksum = int(data[-2:], 16)
    
    return calculated_sum == file_checksum

# 在构建脚本中使用
def add_hex_verification(env):
    """添加HEX文件验证"""
    
    def verify_after_build(source, target, env):
        hex_file = target[0].get_abspath()
        success, message = verify_hex_file(hex_file)
        
        if success:
            print(f"✓ {message}")
        else:
            print(f"✗ {message}")
            # 可以选择使构建失败
            # env.Exit(1)
    
    env.AddPostAction("$BUILD_DIR/${PROGNAME}.hex", verify_after_build)

4.3 版本控制与持续集成

在团队项目中，确保所有成员使用相同的构建配置至关重要。我推荐以下实践：

1. 将脚本纳入版本控制：所有自定义脚本都应该在Git仓库中
2. 使用环境变量：敏感信息（如路径）通过环境变量配置
3. 创建Makefile或批处理脚本：简化常用命令

# Makefile示例
.PHONY: all build clean flash debug

all: build verify

build:
	pio run

build-release:
	pio run --environment release

verify:
	python scripts/verify_hex.py .pio/build/*/firmware.hex

flash:
	pio run --target upload

clean:
	pio run --target clean

# 为不同环境创建别名
stm32-build:
	pio run --environment genericSTM32F103C8

stc-build:
	pio run --environment STC89C516RD

对于持续集成，可以在GitHub Actions或GitLab CI中配置：

# .github/workflows/build.yml
name: Build and Test

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        environment: [genericSTM32F103C8, STC89C516RD]
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'
    
    - name: Install PlatformIO
      run: |
        python -m pip install --upgrade pip
        pip install platformio
    
    - name: Build
      run: pio run --environment ${{ matrix.environment }}
    
    - name: Verify HEX
      run: |
        HEX_FILE=$(find .pio/build -name "firmware.hex" | head -1)
        if [ -f "$HEX_FILE" ]; then
          python scripts/verify_hex.py "$HEX_FILE"
        else
          echo "HEX file not found"
          exit 1
        fi
    
    - name: Upload artifacts
      uses: actions/upload-artifact@v3
      with:
        name: firmware-${{ matrix.environment }}
        path: .pio/build/${{ matrix.environment }}/firmware.hex

4.4 性能优化与缓存策略

当项目变大时，构建时间可能成为问题。以下是一些优化建议：

增量构建配置：

[env:genericSTM32F103C8]
platform = ststm32
board = genericSTM32F103C8
framework = arduino
build_cache = true  # 启用构建缓存
lib_cache = true    # 启用库缓存

并行构建： PlatformIO默认使用并行构建，但可以通过环境变量控制：

# 使用4个并行任务
export PLATFORMIO_BUILD_FLAGS="-j4"
pio run

# 或者在platformio.ini中设置
[env:genericSTM32F103C8]
build_flags = -j4

选择性生成HEX： 对于开发阶段，可能不需要每次都生成HEX文件：

# 根据环境变量决定是否生成HEX
import os

def conditional_hex_generation(env):
    if os.getenv('GENERATE_HEX', '1') == '1':
        # 生成HEX的逻辑
        setup_hex_generation(env)

4.5 错误处理与日志记录

完善的错误处理和日志记录能极大提高调试效率：

# scripts/error_handler.py
import sys
import traceback
from datetime import datetime

class BuildErrorHandler:
    def __init__(self, log_file="build_errors.log"):
        self.log_file = log_file
        self.error_count = 0
    
    def log_error(self, error_type, message, details=None):
        """记录错误到日志文件"""
        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        
        log_entry = f"[{timestamp}] {error_type}: {message}\n"
        
        if details:
            log_entry += f"详细信息: {details}\n"
        
        log_entry += "-" * 80 + "\n"
        
        with open(self.log_file, "a") as f:
            f.write(log_entry)
        
        self.error_count += 1
    
    def handle_hex_generation_error(self, env, exception):
        """处理HEX生成错误"""
        error_msg = str(exception)
        
        # 常见错误模式匹配
        if "objcopy" in error_msg and "not found" in error_msg:
            self.log_error("工具链错误", 
                          "objcopy工具未找到",
                          f"请检查工具链安装: {error_msg}")
            
            # 尝试使用备用方法
            self.try_alternative_hex_generation(env)
        
        elif "checksum" in error_msg.lower():
            self.log_error("校验和错误",
                          "HEX文件校验和计算失败",
                          error_msg)
        
        else:
            self.log_error("未知错误",
                          "HEX生成过程中发生未知错误",
                          f"{error_msg}\n{traceback.format_exc()}")
    
    def try_alternative_hex_generation(self, env):
        """尝试备用的HEX生成方法"""
        try:
            # 方法1: 使用Python实现HEX生成
            self.generate_hex_with_python(env)
            
        except Exception as e:
            # 方法2: 使用系统工具
            self.generate_hex_with_system_tools(env)
    
    def generate_hex_with_python(self, env):
        """使用Python生成HEX文件"""
        print("尝试使用Python生成HEX文件...")
        
        # 读取ELF文件并转换为HEX格式
        # 这里需要实现ELF到HEX的转换逻辑
        pass
    
    def report_summary(self):
        """报告错误摘要"""
        if self.error_count == 0:
            print("✓ 所有构建任务完成，未发现错误")
        else:
            print(f"⚠ 构建完成，发现{self.error_count}个错误，详情请查看{self.log_file}")

# 在脚本中使用
error_handler = BuildErrorHandler()

try:
    setup_hex_generation(env)
except Exception as e:
    error_handler.handle_hex_generation_error(env, e)
finally:
    error_handler.report_summary()

通过这套完整的解决方案，我成功地在多个项目中实现了可靠的HEX文件生成。无论是简单的STM32项目，还是复杂的多平台项目，这套方案都能提供稳定、可配置的HEX生成功能。最重要的是，它解决了从传统IDE迁移到PlatformIO时遇到的实际问题，让开发者能够专注于代码本身，而不是构建系统的细节。