工程化Python脚本需解决模块导入、CLI参数、配置加载和日志四类问题：①入口加sys.path.insert(0,当前目录)；②argparse用add_subparsers+root级全局参数；③配置按命令行>环境变量>文件优先级合并；④日志用标准logging+JSON格式+run_id注入。
脚本直接 import 会炸，因为没设 PYTHONPATH
很多 Python 脚本跑得好好的，一放到工程里就报 ModuleNotFoundError，根本原因是运行时工作目录和模块搜索路径不一致。不是所有项目都用 pip install -e .，尤其内部工具或快速验证场景，更依赖手动调整导入路径。
实操建议：
- 在入口脚本顶部加
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))，确保当前目录优先被搜到 - 避免用
os.chdir()切换目录后再 import —— 这会让相对导入失效、__file__指向错乱 - 如果用
python -m mypackage.main启动，必须保证该包在sys.path中（比如当前目录有__init__.py），否则-m找不到模块 - CI/CD 或容器中不要依赖 shell 的
cd来“模拟开发环境”，应显式控制PYTHONPATH或用pathlib.Path(__file__).parent.parent构造路径
argparse 参数冲突：子命令和全局选项混着写就挂
工程化后 CLI 工具必然分功能模块（如 python cli.py train --lr 1e-3 和 python cli.py eval --model path.pth），但很多人把通用参数（如 --verbose、--config）和子命令参数写在同一层，结果 argparse 解析失败或默认值覆盖异常。
关键点：
立即学习“Python免费学习笔记（深入）”；
- 用
add_subparsers(dest='command')创建子命令，再对每个subparser单独调用add_argument() - 全局参数（所有子命令都支持）必须加在 root parser 上，且设置
nargs='?'或default=argparse.SUPPRESS，避免子命令未指定时传空值 - 别在子 parser 上重复定义同名参数（如两个子命令都加
--device），会导致解析歧义；统一提到 root 层或用不同名字 - 调试时打印
args看结构：print(vars(args))，确认command字段存在且值正确
配置文件加载顺序混乱：pydantic-settings 不是万能解药
从硬编码到 config.yaml 再到环境变量注入，配置管理最容易出问题的地方不是语法，而是**加载优先级和作用域**。比如本地开发用 YAML，测试环境靠 ENV=staging，生产却漏了 --config /etc/app/prod.toml，结果连数据库地址都还是 dev 的。
推荐做法：
- 明确三档优先级：命令行参数 > 环境变量 > 配置文件，并在代码里按此顺序合并（不要全交给
pydantic-settings自动猜） - 配置文件路径本身也应可配：先查
APP_CONFIG环境变量，再 fallback 到./config.yaml，最后是~/.myapp/config.yaml - 用
pydantic.BaseSettings时禁用env_file（它只读 .env，不处理系统级 env），改用field(default_factory=lambda: os.getenv('LOG_LEVEL', 'INFO')) - 启动时打印最终生效的配置项（仅 log level ≥ DEBUG），字段值用
***掩码敏感字段，避免日志泄露密钥
日志不能只 print，但也不必一上来就上 structlog
脚本阶段 print 没问题，工程化后要能过滤、切分、上报、关联 trace ID。但直接引入 structlog + opentelemetry 容易卡在序列化或上下文传递上，尤其多进程或异步任务中 logger 实例丢失。
渐进式方案：
- 先统一用标准
logging，配置Formatter输出 JSON（用json.dumps包一层），字段至少含level、time、module、funcName、message - 进程启动时生成唯一
run_id，通过LoggerAdapter注入到每条日志，不用改业务代码里的logger.info() - 异步任务（如
asyncio或 Celery）需显式绑定 context：Celery 用task.after_return注入，asyncio用contextvars.ContextVar存 trace_id - 别在
__del__或atexit里 flush 日志 handler —— 可能已被 GC，改用logging.shutdown()在主流程末尾显式调用
