| title | i18nReady |
|---|---|
Comandos da CLI |
true |
import Since from '/components/Since.astro';
import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';
Você pode utilizar a Interface de Linha de Comando (CLI) providenciada pelo Astro para desenvolver, fazer build e pré-visualizar seu projeto a partir de uma janela de terminal.
Use a CLI ao executar um dos comandos documentados nessa página com seu gerenciador de pacotes preferido, opcionalmente seguido de algumas flags. Flags customizam o comportamento de um comando.
Um dos comandos que você vai usar com mais frequência é astro dev. Esse comando inicia o servidor de desenvolvimento e dá a você uma pré-visualização ao vivo e atualizada do seu site em um navegador conforme você trabalha:
Você pode digitar astro --help no seu terminal para exibir uma lista de todos os comandos disponíveis:
A seguinte mensagem vai aparecer no seu terminal:
astro [comando] [...flags]
Comandos
add Adiciona uma integração.
build Faz build do seu projeto e escreve ele no disco.
check Checa seu projeto por erros.
dev Inicia o servidor de desenvolvimento.
docs Abre a documentação no seu navegador da web.
info Lista informações sobre sua configuração atual do Astro.
preview Pré-visualiza sua build localmente.
sync Gera tipos de coleção de conteúdo.
preferences Configura as preferências do usuário.
telemetry Configura opções de telemetria.
Flags Globais
--config <path> Especifica seu arquivo de configuração.
--root <path> Especifica a pasta raiz do seu projeto.
--site <url> Especifica o site do seu projeto.
--base <pathname> Especifica a base do seu projeto.
--verbose Habilita logs verbosos.
--silent Desabilita todos os logs.
--version Mostra o número da versão e sai.
--open Abre o aplicativo no navegador quando o servidor iniciar.
--help Mostra essa mensagem de ajuda.:::note
Os -- extras antes de qualquer flag são necessários para que o npm passe suas flags para o comando astro.
:::
Você também pode usar scripts no package.json para versões mais curtas desses comandos. Usando um script permite você usar os mesmos comandos que você pode estar familiarizado com outros projetos, como o npm run build.
Os seguintes scripts para os comandos astro comuns (astro dev, astro build e astro preview) são adicionados pra você automaticamente quando você cria um projeto usando o assistente create astro.
Quando você segue as instruções para instalar o Astro manualmente, você é instruído a adicionar esses scripts você mesmo. Você também pode adicionar mais scripts para essa lista manualmente para qualquer comando que você usa frequentemente.
{
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"preview": "astro preview"
}
}Você vai frequentemente usar esses comandos astro ou scripts que executam eles, sem nenhuma flag. Adicione flags para o comando quando você quer customizar o comportamento do comando. Por exemplo, você pode querer iniciar o servidor de desenvolvimento em uma porta diferente ou fazer a build do seu site com logs verbosos para depuração.
npm run build -- --verbose
</Fragment>
<Fragment slot="pnpm">
```shell
# executa o servidor de desenvolvimento na porta 8080 usando o script `start` no `package.json`
pnpm start --port 8080
# faz build do seu site com logs verbosos usando o script `build` script no `package.json`
pnpm build --verbose
yarn build --verbose
</Fragment>
</PackageManagerTabs>
{/*
CONTEÚDO ORIGINAL Que Nós Podemos Sempre reverter se as coisas novas são muito amigáveis
Você pode utilizar a interface de linha de comando (CLI) oferecida pelo Astro para desenvolver, fazer build e visualizar seu projeto a partir de uma janela de terminal.
Use a CLI ao executar um dos **comandos** documentados nessa página, opcionalmente seguido de algumas **flags**. Flags customizam o comportamento de um comando. Por exemplo, para iniciar o servidor de desenvolvimento na porta `8080`, você combinaria o comando `astro dev` com a flag `--port`: `astro dev --port 8080`.
Na maioria dos casos você usará a CLI pelo seu gerenciador de pacotes:
<PackageManagerTabs>
<Fragment slot="npm">
```shell
npx astro dev --port 8080
Se você iniciou seu projeto utilizando o assistente create astro, você pode também utilizar os scripts em package.json para uma versão mais curta desses comandos. Veja o README.md no seu projeto para detalhes sobre quais comandos estão disponíveis.
*/}
Executa o servidor de desenvolvimento do Astro. Ele é um servidor HTTP local que não faz bundle de assets. Ele utiliza Hot Module Replacement (HMR) para atualizar seu navegador assim que você salva mudanças no seu editor.
Faz a build do seu site para deploy. Por padrão, este comando irá gerar arquivos estáticos que serão colocados no diretório dist/. Se SSR estiver habilitado, o comando irá gerar os arquivos de servidor necessários para servir o seu website.
Pode ser combinado com as flags comuns documentadas abaixo.
Inicia um servidor local para servir o conteúdo do seu diretório estático (dist/ por padrão) criado pela execução do comando astro build.
Esse comando permite que você visualize seu site localmente após o build para detectar quaisquer erros no resultado final do build antes de fazer o deploy. Ele não foi projetado para ser executado em produção. Para obter ajuda com a hospedagem de produção, consulte nosso guia Faça deploy do seu site Astro.
Desde o Astro 1.5.0, astro preview também funciona para builds SSR se você utiliza um adaptador que o suporta. Atualmente, apenas o adaptador para Node suporta astro preview.
Pode ser combinado com as flags comuns documentadas abaixo.
Roda diagnósticos (como checar a tipagem de arquivos .astro) em seu projeto e reporta erros no console. Se algum error for encontrado durante o processo, ele será finalizado com o código 1.
Esse comando foi feito para ser usado em fluxos de trabalho de CI.
Use estas flags para customizar o comportamento do comando.
O comando observará qualquer alteração em seu projeto e comunicará qualquer erro.
Leia mais sobre checagem de tipos no Astro.
:::tip
Executar astro dev, astro build ou astro check irá executar o comando sync também.
:::
Gera tipos do TypeScript para todos os módulos do Astro. Ele configura um arquivo src/env.d.ts para inferência de tipos e define módulos para funcionalidades que dependam de topos gerados:
- O módulo
astro:contentpara a API de Coleções de Conteúdo. - O módulo
astro:dbpara o Astro DB.
Adiciona uma integração a sua configuração. Leia mais no guia de integrações.
Abre o website da documentação do Astro diretamente do seu terminal.
Reporta informações úteis sobre seu ambiente do Astro atual. Útil para fornecer informações ao abrir uma issue.
astro infoExemplo de saída:
Astro v3.0.12
Node v20.5.1ptb
System macOS (arm64)
Package Manager pnpm
Output server
Adapter @astrojs/vercel/serverless
Integrations none
Gerencie as preferências do usuário com o comando astro preferences. As preferências do usuário são específicas para usuários individuais do Astro, ao contrário do arquivo astro.config.mjs, que altera o comportamento para todos que estão trabalhando em um projeto.
As preferências do usuário têm como escopo o projeto atual por padrão, armazenado em um arquivo local .astro/settings.json.
Usando a flag --global, as preferências do usuário também podem ser aplicadas a todos os projetos do Astro na máquina atual. As preferências globais do usuário são armazenadas em um local específico do sistema operacional.
devToolbar— Ativa ou desativa a barra de ferramentas de desenvolvimento no navegador. (Padrão:true)checkUpdates— Ativa ou desativa as verificações automáticas de atualização da CLI do Astro. (Padrão:true)
O comando list imprime as definições atuais de todas as preferências configuráveis do usuário. Ele também oferece suporte a uma saída --json legível por máquina.
astro preferences listExemplo de saída do terminal:
| Preference | Value |
|---|---|
| devToolbar.enabled | true |
| checkUpdates.enabled | true |
Você pode "ativar" (enable), "desativar" (disable) ou "redefinir" (reset) as preferências para o padrão.
Por exemplo, para desativar a barra de ferramentas de desenvolvimento em um projeto específico do Astro:
astro preferences disable devToolbarPara desativar a barra de ferramentas de desenvolvimento em todos os projetos do Astro na máquina atual:
astro preferences disable --global devToolbarA barra de ferramentas de desenvolvimento pode ser ativada posteriormente com:
astro preferences enable devToolbarO comando reset redefine uma preferência para seu valor padrão:
astro preferences reset devToolbarDefine a configuração de telemetria para o usuário atual da CLI. Telemetria são dados anônimos que fornecem à equipe do Astro insights sobre quais recursos do Astro são usados com mais frequência. Para obter mais informações, consulte a página de telemetria do Astro.
Telemetria pode ser desabilitada com esse comando da CLI:
astro telemetry disableTelemetria pode ser posteriormente habilitada com:
astro telemetry enableO comando reset redefine os dados de telemetria:
astro telemetry reset:::tip[Gostaria de desabilitar telemetria em ambientes de CI?]
Adicione o comando astro telemetry disable em seus scripts de CI ou defina a variável de ambiente ASTRO_TELEMETRY_DISABLED.
:::
Especifica o caminho para a raiz do projeto. Se não for especificado, o diretório de trabalho atual é assumido como a raiz.
A raiz é utilizada para encontrar o arquivo de configuração Astro.
astro --root minhaPastaRaiz/minhaPastaDoProjeto devEspecifica o caminho para o arquivo de configuração relativo a raiz do projeto. Por padrão, astro.config.mjs. Use isso se você utiliza um nome diferente para o seu arquivo de configuração ou se você tem seu arquivo de configuração em outra pasta.
astro --config config/astro.config.mjs devConfigura a opção outDir do seu projeto. A passagem dessa flag substituirá o valor de outDir em seu arquivo astro.config.mjs, se um existir.
Configura a opção site para seu projeto. Passar essa flag irá sobrescrever o valor de site no seu arquivo astro.config.mjs, se um existir.
Configura a opção base para seu projeto. Passar essa flag irá sobrescrever o valor de base no seu arquivo astro.config.mjs, se um existir.
Especifica em qual porta executar o servidor de desenvolvimento e o servidor de pré-visualização. O valor padrão é 4321.
Define em quais endereços IP de rede o servidor de desenvolvimento e o servidor de pré-visualização devem escutar (ou seja, IPs de hosts não locais). Isso pode ser útil para testar seu projeto em dispositivos locais, como um telefone celular, durante o desenvolvimento.
--host— escute em todos os endereços, incluindo endereços LAN e públicos--host <endereco-personalizado>— exponha em um endereço IP de rede em<endereco-personalizado>
:::caution
Não use a flag --host para expor o servidor de desenvolvimento e o servidor de pré-visualização em um ambiente de produção. Os servidores foram projetados para uso local somente durante o desenvolvimento do seu site.
:::
Habilita logging verboso, que é útil para depurar um problema.
Habilita logging silencioso, que irá executar o servidor sem nenhuma saída do terminal.
Utilize essas flags para conseguir informação sobre a CLI astro.
Mostra o número de versão do Astro.
Abre automaticamente o aplicativo no navegador na inicialização do servidor. Pode ser passada uma URL completa (por exemplo, --open http://exemplo.com) ou um nome de caminho (por exemplo, --open /sobre) para especificar a URL a ser aberta.
Mostra a mensagem de ajuda e sai.
Se você precisa de mais controle ao executar Astro, o pacote "astro" também exporta APIs para programaticamente executar os comandos da CLI.
Essas APIs são experimentais e a assinatura de suas APIs podem mudar. Quaisquer atualizações serão mencionadas no registro de mudanças do Astro e a informação abaixo irá sempre mostrar a informação atual e atualizada.
O tipo AstroInlineConfig é usado para todas as APIs de comandos abaixo. Ela se estende do tipo da configuração do Astro do usuário:
interface AstroInlineConfig extends AstroUserConfig {
configFile?: string | false;
mode?: "development" | "production";
logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}
Tipo: string | false
Padrão: undefined
Um caminho customizado para o arquivo de configuração do Astro.
Se esse valor é undefined (padrão) ou ausente, Astro irá procurar por um arquivo astro.config.(js,mjs,ts) relativo ao root e irá carregar o arquivo de configuração, se encontrado.
Se um caminho relativo é definido, ele será resolvido com base no diretório de trabalho atual.
Defina para false para desabilitar o carregamento de quaisquer arquivos de configuração.
A configuração inline passada nesse objeto irá tomar a maior prioridade ao ser combinada com a configuração do usuário carregada.
Tipo: "development" | "production"
Padrão: "development" quando executar astro dev, "production" quando executar astro build
O modo utilizado ao fazer build do seu site para gerar um código de "desenvolvimento" ou "produção".
Tipo: "debug" | "info" | "warn" | "error" | "silent"
Padrão: "info"
O nível de logging para filtrar mensagens registradas pelo Astro.
"debug": Registre tudo, incluindo diagnósticos barulhentos de depuração."info": Registre mensagens informacionais, avisos e erros."warn": Registre avisos e erros."error": Registre apenas erros."silent": Sem registros.
Tipo: (inlineConfig: AstroInlineConfig) => AstroDevServer
Similar ao astro dev, ele executa o servidor de desenvolvimento do Astro.
import { dev } from "astro";
const servidorDev = await dev({
root: "./meu-projeto",
});
// Pare o servidor, se necessário
await servidorDev.stop();Tipo: (inlineConfig: AstroInlineConfig) => void
Similar ao astro build, ele faz build do seu site para deploy.
import { build } from "astro";
await build({
root: "./meu-projeto",
});Tipo: (inlineConfig: AstroInlineConfig) => AstroPreviewServer
Similar ao astro preview, ele inicia um servidor local para servir seu diretório dist/ estático.
import { preview } from "astro";
const servidorPreview = await preview({
root: "./meu-projeto",
});
// Pare o servidor, se necessário
await servidorPreview.stop();Tipo: (inlineConfig: AstroInlineConfig) => number
Similar ao astro sync, ele gera tipos do TypeScript para todos os módulos do Astro
import { sync } from "astro";
const codigoSaida = await sync({
root: "./meu-projeto",
});
process.exit(codigoSaida)Autentica com o Astro Studio. Isso é necessário para executar todos os comandos de gerenciamento de banco de dados, incluindo astro link.
Vincula seu banco de dados hospedado no Studio. Isso é necessário para executar comandos do Astro DB para o gerenciamento do banco de dados. Para vincular um banco de dados, você será solicitado a selecionar um banco de dados existente ou criar um novo.
Faz logout do Astro Studio e remove todas as chaves de autenticação armazenadas localmente.