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.0"run:|#!/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:"latest"run:|echo "部署到{{env}}，版本{{version}}"

2. 标志参数（适合开关选项）

parameters:-name:dry-runtype:booleandefault:false# 别这样写：用--dry-run而不是-dry-runflag:--dry-runrun:|if [ "{{dry-run}}" = "true" ]; then echo "模拟运行模式" fi

3. 交互式参数（适合敏感信息）

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。安装后自动注册：

npminstall@team/codex-deploy-commands --save-dev

然后在codex.json里声明依赖。好处是版本管理清晰，坏处是每次更新都要发版。

方案三：环境变量注入（临时方案）
通过CODEX_COMMANDS_DIR环境变量指定命令目录。适合CI/CD场景，但别用在开发环境——我见过有人把生产环境的命令路径写死在Dockerfile里，结果本地调试时找不到命令。

团队复用的最佳实践：血泪教训

1. 命名规范要统一：deploy-staging比deployStaging好，db:migrate比db_migrate好。CodeX支持冒号作为命名空间分隔符，比如project:deploy:staging。

2. 版本号必须写：不写version字段，CodeX会默认用缓存版本。我遇到过团队里有人改了命令但没改版本号，其他人sync后还是旧版本。

3. 错误处理要友好：别让用户看到Python的traceback。用trap捕获错误，输出中文提示。比如：

trap'echo "❌ 部署失败，请检查：\n1. 网络连接\n2. 权限配置\n3. 环境变量"'ERR

4. 测试命令要独立：写一个test:all命令，批量运行所有自定义命令的单元测试。我习惯在每个命令文件里加一个test字段：

test:|codex run deploy-staging --env test --dry-run # 这里检查输出是否包含"模拟运行模式"

5. 文档即代码：在命令文件里用description字段写清楚用法，别单独写README。我见过有人命令改了，文档没更新，新人照着文档操作直接炸了。

个人经验性建议

如果你刚开始做自定义命令，别追求一次性完美。先写一个能用的版本，跑通流程，再逐步加参数、加错误处理。我见过太多人花三天设计一个“通用”命令，结果用了一次就再也没碰过。

另外，命令的scope要谨慎。local只对当前项目生效，global对所有项目生效。我建议默认用local，除非你确定这个命令在所有项目里都通用。否则，一个global的命令可能会和另一个项目的命令冲突，到时候排查起来想死的心都有。

最后，定期清理无用命令。我每季度会跑一次codex command list --orphan，找出那些三个月没被调用的命令，要么归档，要么删除。命令多了，查找效率反而下降。

记住：自定义命令是为了提升效率，不是为了炫技。一个命令如果写完后还要花十分钟解释怎么用，那还不如直接手敲命令。