Herramienta de formato de OpenCode

OpenCode, después de cada escritura o edición de archivos,automáticamenteutiliza la herramienta de formato del lenguaje correspondiente para formatearlo, asegurando que el código generado siempre cumpla con el estilo de código de tu proyecto. Todo el proceso se completa silenciosamente en segundo plano, sin necesidad de ninguna operación manual.

Principio de funcionamiento

Cuando OpenCode escribe o edita un archivo, ejecuta automáticamente el formato siguiendo los siguientes pasos:

  1. Detecta la extensión del archivo escrito o editado (como.ts、.py、.goetc.)
  2. Compara la extensión con todas las herramientas de formato habilitadas
  3. Ejecuta el comando de formato coincidente sobre ese archivo
  4. Vuelve a escribir automáticamente el resultado del formato en el archivo

Por ejemplo, si tu proyectopackage.jsoncontieneprettierdependencias, OpenCode lo detectará automáticamente y, después de cada edición de.js、.ts、.cssarchivos como estos, invocará prettier para formatearlos, sin necesidad de ninguna configuración adicional.

Herramientas de formato integradas

OpenCode incorpora soporte integrado para herramientas de formato que cubren los principales lenguajes y frameworks, divididas en dos categorías:

  • Se habilita si el comando está disponible: solo necesitas instalar el comando correspondiente en el sistema y OpenCode lo detectará y utilizará automáticamente
  • Requiere un archivo de configuración o dependencia del proyecto: se necesita incluir un archivo de configuración o paquete de dependencias específico en el proyecto
Herramienta de formato Extensiones de archivo admitidas Requisito de habilitación
air .R airComando disponible
biome .js .jsx .ts .tsx .html .css .md .json .yamly más El proyecto contienebiome.jsonobiome.jsoncarchivo de configuración
cargofmt .rs cargo fmtComando disponible
clang-format .c .cpp .h .hpp .inoy más El proyecto contiene.clang-formatarchivo de configuración
cljfmt .clj .cljs .cljc .edn cljfmtComando disponible
dart .dart dartComando disponible
dfmt .d dfmtComando disponible
gleam .gleam gleamComando disponible
gofmt .go gofmtComando disponible
htmlbeautifier .erb .html.erb htmlbeautifierComando disponible
ktlint .kt .kts ktlintComando disponible
mix .ex .exs .eex .heex .leex .neex .sface mixComando disponible
nixfmt .nix nixfmtComando disponible
ocamlformat .ml .mli ocamlformatComando disponible, y el proyecto contiene.ocamlformatarchivo de configuración
ormolu .hs ormoluComando disponible
oxfmt(Experimental) .js .jsx .ts .tsx package.jsoncontieneoxfmtdependencia, y se ha establecido el flag de variable de entorno experimental correspondiente
pint .php composer.jsoncontienelaravel/pintdependencia
prettier .js .jsx .ts .tsx .html .css .md .json .yamly más package.jsoncontieneprettierdependencia
rubocop .rb .rake .gemspec .ru rubocopComando disponible
ruff .py .pyi ruffComando disponible y existe la configuración correspondiente
rustfmt .rs rustfmtComando disponible
shfmt .sh .bash shfmtComando disponible
standardrb .rb .rake .gemspec .ru standardrbComando disponible
terraform .tf .tfvars terraformComando disponible
uv .py .pyi uvComando disponible
zig .zig .zon zigComando disponible

Cuando varias herramientas de formato admiten la misma extensión (por ejemplo,.rses compatible también concargofmtyrustfmt, y.rbes compatible también conrubocopystandardrb)

Estructura del archivo de configuración

La configuración personalizada de las herramientas de formato se escribe en elopencode.jsondeformattercampo, el nombre de la clave es el nombre de la herramienta de formato (coincide con el nombre en la tabla integrada), y el valor es el objeto de configuración de la herramienta:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    // Nombre de la herramienta de formato: objeto de configuración
    "prettier": {
      // Completa aquí las opciones de configuración de prettier
    }
  }
}

Cada herramienta de formato admite las siguientes opciones de configuración:

Opción de configuración Tipo Descripción
disabled boolean Definir comotruedeshabilita esta herramienta de formato; el resto de opciones de configuración se ignorarán
command string[] Matriz de comandos para ejecutar el formato. En el comando se puede usar el$FILEcomo marcador de posición; en tiempo de ejecución se reemplazará por la ruta completa del archivo a formatear
environment object Variables de entorno inyectadas al ejecutar la herramienta de formato, en forma de pares clave-valor
extensions string[] Lista de extensiones de archivo que procesa esta herramienta de formato (incluye el., como".ts"）

Deshabilitar herramientas de formato

1. Deshabilitar todas las herramientas de formato

Si no deseas que OpenCode formatee automáticamente ningún archivo, puedes establecer elformatterdirectamente enfalse：

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
"formatter": false // Deshabilita globalmente todas las herramientas de formato; no se realizará ningún formato después de escribir el archivo
}

2. Deshabilitar una herramienta de formato específica

Si solo necesitas deshabilitar una herramienta de formato concreta, en el objeto de configuración de la herramienta correspondiente, define eldisabledcomotrue, las demás herramientas de formato no se ven afectadas:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
"disabled": true // Solo deshabilita prettier; las demás herramientas de formato (como ruff, gofmt) siguen funcionando con normalidad
    }
  }
}

Herramientas de formato personalizadas

Mediante la opcióncommand、environmentyextensionsde configuración, puedes sobrescribir el comportamiento predeterminado de las herramientas de formato integradas o añadir herramientas de formato que OpenCode aún no tiene integradas.

1. Sobrescribir el comando de las herramientas de formato integradas

Por ejemplo, especifica parámetros concretos para prettier y limítalo a que procese únicamente extensiones específicas:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      // $FILE en la matriz command es un marcador de posición que, en tiempo de ejecución, se reemplazará por la ruta completa del archivo a formatear
      // Ejemplo de ejecución real: npx prettier --write /your/project/src/index.ts
      "environment": {
        "NODE_ENV": "development"    // Variables de entorno inyectadas al ejecutar prettier
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
      // Sobrescribe las extensiones predeterminadas: solo ejecuta prettier en estos cuatro tipos de archivo, no procesa .html, .css, etc.
    }
  }
}

2. Añadir herramientas de formato personalizadas

Si la herramienta de formato que usas no está en la lista integrada, puedes añadirla especificando un nombre arbitrario. Basta con proporcionar el comando de inicio y las extensiones de archivo a procesar:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "custom-markdown-formatter": {    // Nombre personalizado (nómbralo arbitrariamente, siempre que no entre en conflicto con las herramientas integradas)
      "command": ["deno", "fmt", "$FILE"],
      // Usa deno fmt para formatear el archivo; $FILE se reemplazará por la ruta real del archivo
      "extensions": [".md"]           // Ejecuta esta herramienta de formato solo en archivos .md
    }
  }
}

3. Configurar varias herramientas de formato a la vez

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    },
    "ruff": {
      "disabled": true    // El proyecto no usa ruff, así que lo deshabilitamos
    },
    "custom-markdown-formatter": {
      "command": ["deno", "fmt", "$FILE"],
      "extensions": [".md"]
    }
  }
}
Otras extensiones