企业官网建设流程全解析

025、自定义 Slash Command：别名到带参数复杂命令的开发

从一次凌晨告警说起

凌晨两点，手机震了。生产环境的日志告警显示某个微服务的错误率突然飙升到15%。我下意识想敲kubectl get pods -n production | grep error，但手边只有手机终端，连上跳板机后还得先查集群上下文。那一刻我意识到：如果有个/prod-error命令能直接帮我查最近5分钟的错误日志，我至少能少敲20个字符、少等两次命令回显。

这就是 Slash Command 的价值——不是炫技，是救命。

别把 Slash Command 当别名用

很多人第一次接触 Claude Code 的自定义命令时，会写成这样：

# 别这样写，这只是一个别名commands:/deploy:description:"部署服务"command:"kubectl apply -f deploy.yaml"

这本质上就是个 shell alias，毫无灵魂。真正的 Slash Command 应该能接受参数、处理上下文、甚至调用外部 API。我们来看一个生产级别的例子。

带参数命令的骨架

先搭一个能处理参数的/rollback命令，用于回滚部署：

commands:/rollback:description:"回滚指定服务到历史版本"arguments:-name:"service"description:"服务名称，如 user-service"required:true-name:"revision"description:"目标版本号，不传则回滚到上一个版本"required:falsedefault:"previous"command:|# 这里踩过坑：必须显式处理参数为空的情况 SERVICE="{{service}}" REVISION="{{revision}}"if["$REVISION" = "previous"]; then echo "正在回滚 $SERVICE 到上一个版本..." kubectl rollout undo deployment/$SERVICE-n production else echo "正在回滚 $SERVICE 到版本 $REVISION..." kubectl rollout undo deployment/$SERVICE--to-revision=$REVISION-n production fi# 等待30秒看状态，别直接退出sleep 30 kubectl rollout status deployment/$SERVICE-n production

注意{{service}}和{{revision}}这种模板语法——Claude Code 会在执行前把用户输入填充进去。如果用户只输入/rollback user-service，revision就会自动取默认值previous。

复杂命令：多步骤 + 条件判断

单行命令好写，但真实场景往往是多步骤的。比如/hotfix命令，需要先拉代码、改版本号、构建镜像、推送到仓库、再部署：

commands:/hotfix:description:"紧急修复：修改代码、构建镜像并部署"arguments:-name:"service"description:"服务名"required:true-name:"branch"description:"修复分支名"required:true-name:"version"description:"新版本号，如 v1.2.3"required:truecommand:|SERVICE="{{service}}" BRANCH="{{branch}}" VERSION="{{version}}"# 第一步：拉取代码并切分支echo ">>> 拉取 $SERVICE 代码，分支:$BRANCH" cd /workspace/$SERVICE git fetch origin git checkout-b $BRANCH origin/main||{echo "分支创建失败，可能已存在"; exit 1;}# 第二步：修改版本号文件# 这里踩过坑：不同项目版本号文件位置不一样，得先检测if[-f "VERSION"]; then echo $VERSION>VERSION elif[-f "package.json"]; thensed -i "s/\"version\":\".*\"/\"version\":\"$VERSION\"/" package.json else echo "无法识别版本文件，请手动修改" exit 1 fi# 第三步：构建并推送docker build-t registry.internal/$SERVICE:$VERSION . docker push registry.internal/$SERVICE:$VERSION# 第四步：部署kubectl set image deployment/$SERVICE $SERVICE=registry.internal/$SERVICE:$VERSION-n production echo ">>>热修复完成，版本 $VERSION 已部署"

这个命令里用了|| { ...; exit 1; }这种 bash 错误处理——别指望 Claude Code 帮你做错误恢复，它只会按顺序执行你的脚本，失败了就报错。所以每一步都要自己兜底。

参数校验：别让用户乱填

用户输入是不可信的。我见过有人把/deploy命令的namespace参数填成; rm -rf /——虽然 Claude Code 有沙箱，但养成校验习惯没坏处：

commands:/deploy:arguments:-name:"namespace"description:"命名空间"required:true# 这里用正则限制只允许小写字母和连字符pattern:"^[a-z0-9-]+$"-name:"image_tag"description:"镜像标签"required:truepattern:"^v[0-9]+\\.[0-9]+\\.[0-9]+$"command:|NAMESPACE="{{namespace}}" TAG="{{image_tag}}"# 双重校验：正则过滤后还要检查长度if[${#NAMESPACE} -gt 63 ]; thenecho "命名空间长度不能超过63个字符" exit 1 fi kubectl set image deployment/app app=myapp:$TAG-n $NAMESPACE

pattern字段是 Claude Code 内置的校验机制，但别完全依赖它——有些版本的正则引擎实现有差异，我遇到过 pattern 没生效的情况，所以脚本里又加了一层长度检查。

动态参数：从环境变量和文件读取

有时候参数不是用户输入的，而是从当前环境推断的。比如/status命令，自动检测当前 k8s 上下文：

commands:/status:description:"查看当前集群状态"command:|# 自动获取当前上下文，别让用户手动传 CONTEXT=$(kubectl config current-context 2>/dev/null || echo "unknown") NAMESPACE=$(kubectl config view --minify -o jsonpath='{..namespace}' 2>/dev/null || echo "default")echo "当前集群:$CONTEXT"echo "当前命名空间:$NAMESPACE" echo "---"# 这里踩过坑：有些集群没有 metrics-server，直接 top 会报错if kubectl top nodes&>/dev/null;then echo "节点资源使用:" kubectl top nodes else echo "metrics-server 不可用，跳过资源监控" fi echo "---" echo "异常 Pod:" kubectl get pods--all-namespaces|grep-E "CrashLoopBackOff|Error|ImagePullBackOff"

这个命令没有参数，但通过环境检测实现了“智能”行为。用户只需要敲/status，就能拿到当前上下文的关键信息。

组合命令：调用其他命令

Slash Command 可以互相调用，但别写成递归死循环：

commands:/full-check:description:"完整检查：日志 + 状态 + 资源"command:|echo "=== 开始完整检查 ==="# 调用其他命令（注意：这里用的是 Claude Code 内部机制，不是 shell 管道）/status echo "---" echo "最近错误日志:" /logs--service all--level error--since 5m echo "---" echo "磁盘使用:" df-h /|tail-1

这种组合方式有个坑：被调用的命令如果定义了参数，你必须显式传值。比如/logs命令如果要求--service参数是 required，这里不传就会报错。所以设计命令时，尽量给参数设默认值。

调试技巧：打印执行计划

写复杂命令时，我习惯先打印一遍“执行计划”，让用户确认后再执行：

commands:/migrate-db:description:"数据库迁移（危险操作）"arguments:-name:"direction"description:"迁移方向: up/down"required:trueenum:["up","down"]-name:"steps"description:"迁移步数"required:falsedefault:"1"command:|DIR="{{direction}}" STEPS="{{steps}}"echo "⚠️ 即将执行数据库迁移:"echo " 方向:$DIR"echo " 步数:$STEPS"echo " 数据库:$DATABASE_URL (从环境变量读取)" echo "" echo "输入 YES 确认执行，其他任意键取消:" read CONFIRM if["$CONFIRM"!="YES"]; then echo "已取消" exit 0 fi# 这里踩过坑：migrate 命令的 -steps 参数在不同版本行为不同if["$DIR" = "up"]; then migrate-path /migrations-database "$DATABASE_URL" up $STEPS else migrate-path /migrations-database "$DATABASE_URL" down $STEPS fi

enum字段限制了direction只能取up或down，用户输别的会直接报错。加上确认步骤，防止手滑。

个人经验：别过度设计

写 Slash Command 最容易犯的错是“想太多”。我见过有人给/deploy命令加了十几个参数，包括--rollback-on-failure、--canary-percentage、--timeout……结果团队里没人记得住，最后还是手动敲 kubectl。

我的原则是：一个命令只解决一个痛点。/rollback就只做回滚，/hotfix就只做热修复。如果某个命令的参数超过3个，说明它应该拆成两个命令。

另外，命令的command字段里尽量用 bash 而不是 Claude Code 的 DSL。bash 是通用语言，换到任何 CI/CD 环境都能跑；DSL 绑定在 Claude Code 上，哪天换工具就废了。

最后，所有命令都要加set -e或者显式错误处理。Claude Code 不会帮你回滚失败的操作——它只会告诉你“命令执行失败”，然后让你自己擦屁股。