Go huh 怎么为非交互环境配置可访问表单

如果 Go 程序在 CI、管道或屏幕阅读器环境中运行，huh.Form 不应该继续依赖 TUI 的光标移动和界面重绘。做法是把表单切到可访问模式，再把输入和输出流显式注入：WithAccessible(true) 负责渲染策略，WithInput 和 WithOutput 负责非交互环境的 IO 边界。

官方地址：https://github.com/charmbracelet/huh

对多字段表单，优先在 Form 层启用可访问模式；对 CI 或脚本，再通过 io.Reader 提供有限输入、通过 io.Writer 接收提示。这样既保留交互终端的默认体验，也不会让无 TTY 的任务卡在等待方向键。

先理解 huh 的可访问模式改变了什么

huh 的普通模式建立在 Bubble Tea 的渲染机制上，适合用户在终端里移动光标、选择选项和反复刷新视图。可访问模式的目标不同：它会避免重绘，改用更基础的终端提示，让屏幕阅读器更容易按文本顺序读取字段和反馈。

因此，“非交互环境”不等于把表单删掉，也不等于把所有字段硬编码。它更准确的含义是：程序不再假设用户能看到 TUI，也不再假设输入端支持方向键。表单仍然负责字段顺序、校验和结果收集，只是渲染和 IO 依赖变得更朴素。

用环境变量决定是否开启 accessible

官方 README 给出的思路是用环境变量或配置项控制可访问模式。交互终端默认仍可使用 TUI，CI、屏幕阅读器或明确要求纯文本的环境再打开开关。

package main

import (
    "errors"
    "fmt"
    "os"

    "charm.land/huh/v2"
)

func buildForm(name *string, enabled *bool) *huh.Form {
    return huh.NewForm(
        huh.NewGroup(
            huh.NewInput().
                Title("项目名称").
                Value(name).
                Validate(func(value string) error {
                    // 空名称直接返回字段错误，避免后续任务拿到无效配置。
                    if value == "" {
                        return errors.New("项目名称不能为空")
                    }
                    return nil
                }),
            huh.NewConfirm().
                Title("是否启用").
                Value(enabled),
        ),
    )
}

func main() {
    var name string
    var enabled bool

    accessibleMode := os.Getenv("ACCESSIBLE") != ""
    form := buildForm(&name, &enabled).WithAccessible(accessibleMode)
    if err := form.Run(); err != nil {
        // 把 huh 的运行错误交给进程边界，调用方可以据此终止 CI 任务。
        fmt.Printf("表单运行失败: %v\\n", err)
        os.Exit(1)
    }
    fmt.Printf("name=%s enabled=%t\\n", name, enabled)
}

这里的关键不是把 ACCESSIBLE 写死为 true，而是让部署环境决定模式。这样本地开发仍有完整的 TUI 体验，CI 只需设置 ACCESSIBLE=1 即可切换。WithAccessible 应该作用在表单上，而不是为每个字段重复维护一套分支。

把 Reader 和 Writer 注入到表单

在没有真实终端的环境中，最容易遗漏的是输入输出流。huh 的表单默认使用标准输入和输出；如果任务由脚本、测试夹具或上游管道驱动，就应该通过 WithInput 和 WithOutput 明确替换它们。

func runAccessibleForm(in io.Reader, out io.Writer) (string, bool, error) {
    var name string
    var enabled bool

    form := buildForm(&name, &enabled).
        WithAccessible(true).
        WithInput(in).
        WithOutput(out)

    if err := form.Run(); err != nil {
        // 保留原始错误，便于上层区分 EOF、校验失败和其他输入问题。
        return "", false, fmt.Errorf("运行可访问表单: %w", err)
    }
    return name, enabled, nil
}

func runFromScript() error {
    // 每个回答占一行；脚本输入应有界，避免 CI 因等待 stdin 而挂起。
    input := strings.NewReader("demo\\ny\\n")
    var output bytes.Buffer

    name, enabled, err := runAccessibleForm(input, &output)
    if err != nil {
        return err
    }
    fmt.Printf("name=%s enabled=%t\\n", name, enabled)
    return nil
}

WithInput 接收 io.Reader，所以可以接标准输入、文件、管道或内存字符串；WithOutput 接收 io.Writer，可以把提示写到标准输出、日志缓冲区或测试用的 bytes.Buffer。实际项目中不要把示例输入写死在生产路径，示例只是说明依赖边界。

字段校验仍然要保留

可访问模式只改变渲染和输入方式，不会替你取消业务校验。像项目名称、环境名、端口或确认项这类字段，仍应在字段上使用 Validate，并返回清楚的中文错误。

需要注意两种失败：一是用户输入不满足校验，表单可以继续给出错误提示；二是 Reader 提前结束、IO 出错或表单运行失败，这类错误要从 Run 返回给调用方。不要在库函数里把所有错误打印后吞掉，否则 CI 只能看到一个不可靠的成功退出码。

func requireEnvironment(value string) error {
    // 只接受明确的部署环境名，避免把空值默认为生产环境。
    switch value {
    case "dev", "staging", "prod":
        return nil
    default:
        return fmt.Errorf("环境必须是 dev、staging 或 prod")
    }
}

什么时候用字段级 RunAccessible

如果程序只需要一个输入字段，而不是完整的多页表单，可以直接使用字段的可访问运行方法，并传入自己的 io.Writer 和 io.Reader。这适合一次性确认、单个路径或单个名称的命令行入口。

func askName(in io.Reader, out io.Writer) (string, error) {
    var name string
    field := huh.NewInput().
        Title("项目名称").
        Value(&name)

    // 单字段场景直接指定 IO，避免为了一个输入额外创建 Form。
    if err := field.RunAccessible(out, in); err != nil {
        return "", fmt.Errorf("读取项目名称: %w", err)
    }
    return name, nil
}

多字段场景仍然建议使用 Form.WithAccessible，因为它能统一管理字段顺序、分组和表单级输出；字段级入口更适合很小的命令行交互。

无输入来源时如何避免任务挂起

真正的无人值守任务可能既没有 TTY，也没有上游输入。此时开启可访问模式还不够：程序仍会等待 Reader。常见处理方式是由调用方在进入表单前判断配置是否齐全，满足条件就跳过表单；如果必须询问，则要求调用方显式提供输入文件或管道，并在输入耗尽时返回错误。

可以把策略固定成三条：

• 交互终端：不设置 ACCESSIBLE，沿用 TUI。
• 屏幕阅读器或纯文本终端：设置 ACCESSIBLE=1，使用标准提示。
• CI 或脚本：设置 ACCESSIBLE=1，同时注入有限的 WithInput，不要只设置环境变量。

如果表单的字段都能由命令行参数、配置文件或环境变量确定，优先在调用方直接组装结果；huh 更适合“仍需要询问，但输入设备不适合 TUI”的场景。这样能把交互和无人值守两条路径的边界讲清楚。

配置速查

常见问题

开启 accessible 后是不是就不需要输入了？

不是。它只是不再依赖 TUI 重绘，仍然需要从标准输入或注入的 Reader 获得答案。

能不能只给表单设置 WithInput，不设置 WithAccessible？

可以注入输入，但如果环境没有 TTY，仍可能受普通 TUI 渲染限制。CI 或屏幕阅读器场景应同时打开可访问模式。

校验失败要不要自己重新读取一行？

通常不需要。把规则放在字段的 Validate 中，让 huh 管理提示和重试；只有 Reader、Writer 或表单运行本身失败时，才由调用方处理返回错误。

小结

Go huh 的非交互配置可以归纳为一条清晰链路：用环境变量决定是否启用 accessible，用 Form.WithAccessible 放弃依赖重绘的 TUI，用 WithInput 与 WithOutput 接入脚本或测试流，用 Validate 保留字段规则，并把 Run 的错误交给上层。这样同一份表单定义就能覆盖交互终端、屏幕阅读器和 CI 三种输入环境。