go-toml 2.4.3 的 map 键跳过 UnmarshalText：先读字符串键再转换

给 Go 的命名字符串类型实现了 UnmarshalText，再把它用作 TOML 映射的键，解码却没有进入这个方法。典型表现是 map[SecretKey]string 里的键仍为 raw，而不是自定义转换后应得到的值，且 toml.Unmarshal 返回 nil。

在 github.com/pelletier/go-toml/v2 v2.4.3 中，要分别检查映射键和映射值的处理。某个字段或 value 已能正确调用 TextUnmarshaler，不代表 map key 也经过同一入口。

命名类型先命中了底层种类分支

2.4.3 的 makeMapKey 先根据 kt.Kind() 分支。底层是 string 时直接把原始键名转换成目标类型；整数、无符号整数、浮点数也有自己的转换分支。命名类型虽然有方法，底层种类仍会匹配这些分支，不会继续走后面的接口检查。

指针键和其他种类有另外的 TextUnmarshaler 检查，不能据此概括成“go-toml 完全不支持自定义键”。也不要只把接收者改为指针来反复尝试：正常的 *SecretKey 方法已经存在时，问题仍可能是键分支提前返回。

如果这个方法负责白名单、大小写规范化或拒绝非法名字，跳过调用就不仅是显示差异。要检查落进业务配置的实际键，而不是以 err == nil 作为唯一通过标准。

限定为字符串值映射时，可以分两步读取

当输入契约明确是顶层字符串键、字符串值映射，可以先读取原始键，再由应用显式执行转换。下面把键规范化为大写只是示例业务规则；真实项目应保留自己已有的 UnmarshalText 规则：

package config

import (
    "fmt"
    "strings"

    "github.com/pelletier/go-toml/v2"
)

type Label string

func (k *Label) UnmarshalText(data []byte) error {
    name := strings.ToUpper(string(data))
    if name == "" {
        return fmt.Errorf("empty label")
    }
    *k = Label(name)
    return nil
}

func decodeLabels(data []byte) (map[Label]string, error) {
    var raw map[string]string
    if err := toml.Unmarshal(data, &raw); err != nil {
        return nil, err
    }
    result := make(map[Label]string, len(raw))
    for name, value := range raw {
        var key Label
        if err := key.UnmarshalText([]byte(name)); err != nil {
            return nil, fmt.Errorf("invalid label %q: %w", name, err)
        }
        if _, exists := result[key]; exists {
            return nil, fmt.Errorf("duplicate normalized label %q", key)
        }
        result[key] = value
    }
    return result, nil
}

转换过程中不修改应用正在使用的旧配置；只有整份结果成功后，才按原来的配置切换流程接入。raw 与 RAW 在这份示例规则下会冲突，因此明确报错，不能让 Go map 的遍历顺序决定哪一个值覆盖另一个。

这不是通用 TOML 转换器。嵌套表、数组、非字符串值或指针键需要按真实模型设计，不能先全部转成字符串再丢掉原类型。若自定义方法会改变错误类型或消息，也应保留原来调用方需要的错误契约。

先确认方法真的执行，再检查配置含义

截至 2026 年 10 月 25 日，当前正式 2.4.3 的键转换仍有上述顺序。选择后续版本时，要核对目标正式实现中的 map-key 路径，不把其他位置的 TextUnmarshaler 修正直接当成这条问题已解决。

保留普通键、被拒绝的键、规范化后冲突的两键，以及带特殊字符的合法 TOML 键。预期是方法确实参与转换，错误不被忽略，合法值完整保留，冲突不能静默覆盖。若配置有写回功能，还要分别检查编码规则，不能只验证一次读取后就假定双向格式都兼容。