029、自定义命令开发：创建、参数化、共享与团队复用的最佳实践

029、自定义命令开发创建、参数化、共享与团队复用的最佳实践上周五晚上十一点我盯着终端里那条报错信息看了整整十五分钟——“Command not found: deploy-staging”。明明刚用CodeX的codex command create注册了自定义命令重启终端后却死活找不到。后来发现问题出在命令的scope参数上——我默认用了local但团队其他成员的CodeX版本压根没加载这个作用域。这种坑踩过一次就再也不会忘了。自定义命令的创建别被“模板”骗了CodeX的自定义命令本质上是YAML配置加一段可执行脚本。很多人一上来就复制官方模板结果改得面目全非。我的习惯是先手写一个最小可运行版本。# 命令定义文件~/.codex/commands/deploy-staging.yamlname:deploy-stagingdescription:部署到staging环境自动打tag# 这里踩过坑version字段不写会导致缓存冲突version:1.0.0run:|#!/bin/bash set -e # 别这样写set -e会让管道中的非零退出码直接终止脚本 # 正确做法用trap捕获错误 trap echo 部署失败检查日志; exit 1 ERRecho 开始部署到staging... git tag staging-$(date %Y%m%d-%H%M%S) git push origin--tags# 这里用codex内置变量别手写路径codex run deploy--env staging--config{{CODEX_PROJECT_DIR}}/config/staging.yaml关键点run字段里可以用{{CODEX_PROJECT_DIR}}、{{CODEX_USER}}这些内置变量。我见过有人硬编码/home/xxx/project换台机器就炸了。参数化让命令活起来命令写死了就没意思了。CodeX支持三种参数传递方式我按使用频率排序1. 位置参数最常用parameters:-name:envtype:stringrequired:true# 这里踩过坑没有加description同事不知道传什么description:目标环境staging/production-name:versiontype:stringrequired:falsedefault:latestrun:|echo 部署到{{env}}版本{{version}}2. 标志参数适合开关选项parameters:-name:dry-runtype:booleandefault:false# 别这样写用--dry-run而不是-dry-runflag:--dry-runrun:|if [ {{dry-run}} true ]; then echo 模拟运行模式 fi3. 交互式参数适合敏感信息parameters:-name:api-keytype:secretprompt:请输入API密钥run:|# 这里用环境变量传递别直接拼接到命令里 export API_KEY{{api-key}} curl -H Authorization: Bearer $API_KEY ...共享与复用别让命令烂在本地团队协作时命令共享是最容易出问题的环节。我见过三种方案各有优劣方案一Git仓库集中管理推荐在项目根目录创建.codex/commands/文件夹所有命令放进去。然后在codex.json里配置{commands:{sources:[local,git:https://github.com/team/codex-commands.git]}}这样每个成员codex sync一下就能拿到最新命令。别这样写把命令直接提交到项目代码仓库里会导致不同项目间的命令污染。方案二NPM包分发适合大型团队把命令打包成npm包发布到私有registry。安装后自动注册npminstallteam/codex-deploy-commands --save-dev然后在codex.json里声明依赖。好处是版本管理清晰坏处是每次更新都要发版。方案三环境变量注入临时方案通过CODEX_COMMANDS_DIR环境变量指定命令目录。适合CI/CD场景但别用在开发环境——我见过有人把生产环境的命令路径写死在Dockerfile里结果本地调试时找不到命令。团队复用的最佳实践血泪教训命名规范要统一deploy-staging比deployStaging好db:migrate比db_migrate好。CodeX支持冒号作为命名空间分隔符比如project:deploy:staging。版本号必须写不写version字段CodeX会默认用缓存版本。我遇到过团队里有人改了命令但没改版本号其他人sync后还是旧版本。错误处理要友好别让用户看到Python的traceback。用trap捕获错误输出中文提示。比如trapecho ❌ 部署失败请检查\n1. 网络连接\n2. 权限配置\n3. 环境变量ERR测试命令要独立写一个test:all命令批量运行所有自定义命令的单元测试。我习惯在每个命令文件里加一个test字段test:|codex run deploy-staging --env test --dry-run # 这里检查输出是否包含模拟运行模式文档即代码在命令文件里用description字段写清楚用法别单独写README。我见过有人命令改了文档没更新新人照着文档操作直接炸了。个人经验性建议如果你刚开始做自定义命令别追求一次性完美。先写一个能用的版本跑通流程再逐步加参数、加错误处理。我见过太多人花三天设计一个“通用”命令结果用了一次就再也没碰过。另外命令的scope要谨慎。local只对当前项目生效global对所有项目生效。我建议默认用local除非你确定这个命令在所有项目里都通用。否则一个global的命令可能会和另一个项目的命令冲突到时候排查起来想死的心都有。最后定期清理无用命令。我每季度会跑一次codex command list --orphan找出那些三个月没被调用的命令要么归档要么删除。命令多了查找效率反而下降。记住自定义命令是为了提升效率不是为了炫技。一个命令如果写完后还要花十分钟解释怎么用那还不如直接手敲命令。