核心是先明确用户输入习惯与错误提示策略；add_argument调用顺序决定help中参数排列顺序，非字母序或必需性排序；未设default的可选参数在help中显示default: None属误导，须显式指定default值。

直接上结论：用 argparse 构建命令行工具，核心不是堆参数，而是先想清楚「用户会怎么输」和「出错时该说什么」——这两点没处理好，再全的参数也像在给机器写说明书。

为什么 add_argument 的顺序会影响 help 输出？

help 文本里参数的排列顺序，完全由 add_argument() 的调用顺序决定，不是按字母、也不是按是否必需。很多人把 --verbose 放最后，结果 help 里它挤在最底下，用户一眼看不到。

• 把最常用、最核心的参数（比如 input_file 这种位置参数）放在最前面
• 把互斥组（add_mutually_exclusive_group()）整体插入到相关功能块中间，别拆开
• 如果用了 epilog 或 description，注意它们默认用 RawDescriptionHelpFormatter 才保留换行，否则缩进全乱

如何让 --help 不输出一堆 None 和 default: None？

默认情况下，argparse 对没设 default 的可选参数，help 里显示 default: None，既冗余又误导——用户会以为“可以传 None”，其实根本不能传。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• 所有 --xxx 参数，只要逻辑上存在“不提供即用某值”的语义，必须显式写 default=...，比如 default=False 或 default=[]
• 布尔型开关推荐用 action='store_true' 或 action='store_false'，避免 type=bool ——后者会让 --flag True 和 --flag False 都解析成 True
• 如果某个参数确实不该有默认值（比如必填但又不是位置参数），用 required=True，而不是留空靠报错兜底

ArgumentParser.parse_args() 报错后程序直接退出，怎么捕获并自定义提示？

parse_args() 内部遇到错误（如未知参数、类型错误）会调用 sys.exit()，导致没法做日志、清理或友好重试。这不是 bug，是设计如此——但你可以绕过。

立即学习“Python免费学习笔记（深入）”；

• 改用 parse_known_args() + 手动校验，适合需要深度控制流程的场景
• 更常用的是重写 error() 方法：

  class CustomParser(argparse.ArgumentParser):
      def error(self, message):
          print(f'❌ 错误：{message}')
          self.print_help()
          sys.exit(2)

• 注意：不要在 error() 里 raise 异常再 try-catch，因为 parse_args() 本身不抛异常，它只 exit

真正难的不是写满 20 个 add_argument()，而是判断哪个参数该支持多次（nargs='*'）、哪个该限制取值范围（choices=['a','b']）、哪个该从文件读（type=argparse.FileType('r')）——这些细节一旦定错，用户第一印象就崩了。