Redocly CLI build命令报TypeError，请求技术排查

错误原因 #

TypeError: this.description.search is not a function 本质是你的OpenAPI文件（或引用的子文件）里存在非字符串类型的description字段。Redocly解析时默认认定description是字符串，会调用字符串的search方法，要是字段是数组、对象这类非字符串类型，就会触发这个错误。

排查与修复步骤 #

• 全局检查所有OpenAPI相关文件：遍历每个description字段，确认类型。以下是常见的错误写法：

  # 错误：description是数组
  paths:
    /api/users:
      get:
        description:
          - 获取用户列表
          - 支持分页筛选
  

  # 错误：description是对象
  components:
    schemas:
      User:
        description:
          summary: 用户模型
          details: 包含用户基础信息
  

• 把非字符串的description改成字符串格式：多行内容可以用YAML的多行字符串语法（|）：

  # 正确：多行字符串
  paths:
    /api/users:
      get:
        description: |
          获取用户列表
          支持分页筛选
  

  # 正确：普通字符串
  components:
    schemas:
      User:
        description: 用户模型，包含用户基础信息
  

• 先做语法校验：执行redocly lint openapi.yaml命令，提前排查格式问题，避免build阶段报错。

额外检查点 #

• 更新redoc-cli版本：老旧版本可能存在兼容性问题，执行npm update -g redoc-cli升级到最新稳定版。
• 检查redocly.yaml配置：如果配置了自定义插件或规则，临时禁用可疑项测试，排除插件修改字段解析逻辑的可能。

内容的提问来源于stack exchange，提问作者Nahid Bandi