Resolução de Problemas

Consulte também o guia de resolução de problemas da Rollup para obter mais informações.

Se as sugestões neste documento não funcionarem, tente publicar as questões nas Discussões da GitHub ou no canal de #help da Discord do País de Vite (Vite Land).

CJS

API de Node da CJS da Vite Depreciada

A construção de CJS da API de Node da Vite está depreciada e será removida na Vite 6. Consulte a discussão da GitHub por mais contexto. Nós devemos atualizar os nossos ficheiros ou abstrações para importarem a construção de módulo de ECMAScript da Vite.

Num projeto de Vite básico, devemos nos certificar de que:

1. O conteúdo do ficheiro vite.config.js está a usar a sintaxe de ESM.
2. O ficheiro package.json mais próximo tem "type": "module, ou usa a extensão .mjs ou .mts, por exemplo, vite.config.mjs ou vite.config.mts.

Para os outros projetos, existem algumas abordagens gerais:

• Configurar o ESM como padrão, optar por CJS se necessário: Adicionar "type": "module no package.json do projeto. Todos os ficheiros *.js agora são interpretados como ESM e precisam usar a sintaxe de ESM. Nós podemos renomear um ficheiro com a extensão .cjs para continuar a usar a CJS.
• Manter a CJS como padrão, optar por ESM se necessário: Se o package.json do projeto não tiver "type": "module", todos os ficheiros *.js são interpretados como CJS. Nós podemos renomear um ficheiro com a extensão .mjs para usar o ESM.
• Importar Dinamicamente a Vite: Se precisarmos de continuar a usar a CJS, podemos importar dinamicamente a Vite usando a import('vite'). Isto exige que o nosso código seja escrito num contexto de async, mas ainda deve ser manejável uma vez que a API da Vite é maioritariamente assíncrona.

Se não tivermos a certeza de onde vem o aviso, podemos executar no nosso programa com a opção VITE_CJS_TRACE=true para registar a rasto da pilha:

VITE_CJS_TRACE=true vite dev

Se gostaríamos de ignorar temporariamente o aviso, podemos executar o nosso programa com a opção VITE_CJS_IGNORE_WARNING=true:

VITE_CJS_IGNORE_WARNING=true vite dev

Nota que os ficheiros de configuração da PostCSS ainda não suportam Módulo de ECMAScript + TypeScript (.mts or .ts in "type": "module"). Se estivermos configurações de PostCSS com .ts e "type: "module" adicionado ao package.json, também precisaremos de renomear a configuração de PostCSS para usar .cts.

Interface de Linha de Comando

Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'

O caminho para a pasta do teu projeto talvez inclua &, o qual não funciona com o npm no Windows (npm/cmd-shim#45).

Tu precisarás ou de:

• Mudar para um outro gestor de pacote (por exemplo, pnpm, yarn)
• Remover o & do caminho do teu projeto

Configuração

Este pacote é apenas de Módulo de ECMAScript

Quando importares um pacote somente de módulo de ECMAScript com require, o seguinte erro acontece.

Failed to resolve "foo". This package is ESM only but it was tried to load by require. Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/dependency.js from /path/to/vite.config.js not supported. Instead change the require of index.js in /path/to/vite.config.js to a dynamic import() which is available in all CommonJS modules.

Os módulos de ECMAScript não podem ser carregados pela require por predefinição.

Enquanto esta pode funcionar com uso de --experimental-require-module, ou Node.js >22, ou em outros executores, continuamos a recomendar a conversão da nossa configuração para módulo de ECMAScript:

• adicionar "type": "module" ao package.json mais próximo
• ou renomear vite.config.js ou vite.config.ts para vite.config.mjs ou vite.config.mts.

Servidor de Desenvolvimento

Requisições são Bloqueada para Sempre

Se estiveres utilizando Linux, limites de descritor de ficheiro e limites de inotify podem estar causando o problema. Já que a Vite não empacota a maior parte dos ficheiros, os navegadores podem requisitar muitos ficheiros os quais requerem muitos descritores de ficheiro, ultrapassando o limite.

Para resolver isto:

• Aumente o limite do descritor de ficheiro pelo ulimit

  # Consulte o limite atual
  $ ulimit -Sn
  # Mude o limite (temporário)
  $ ulimit -Sn 10000 # Tu podes também precisar mudar o limite manualmente
  # Reinicie o teu navegador

• Aumente os seguintes limites relacionado com inotify pelo sysctl

  # Consulte os limites atuais
  $ sysctl fs.inotify
  # Mude os limites (temporário)
  $ sudo sysctl fs.inotify.max_queued_events=16384
  $ sudo sysctl fs.inotify.max_user_instances=8192
  $ sudo sysctl fs.inotify.max_user_watches=524288

Se os passos acima não funcionarem, podes tentar adicionar DefaultLimitNOFILE=65536 como uma configuração não comentada aos seguintes ficheiros:

• /etc/systemd/system.conf
• /etc/systemd/user.conf

Para Ubuntu Linux, podes precisar de adicionar a linha * - nofile 65536 para o ficheiro /etc/security/limits.conf ao invés de atualizar os ficheiros de configuração do systemd.

Nota que estas definições persistem mas uma reinicialização é necessária.

Requisições de Rede Impedem o Carregamento

Quando estiveres a usar um certificado de SSL auto-assinado, o Chrome ignora todas diretivas do armazenamento de recurso de consulta imediata (aka, caching) e recarrega o conteúdo. A Vite depende das diretivas de armazenamento de recurso de consulta imediata.

Para resolver o problema use um certificado de SSL de confiança.

Consulte: Cache problems, Chrome issue

macOS

Tu podes instalar um certificado de confiança através da Interface da Linha de Comando com este comando:

security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db your-cert.cer

Ou, importando-o pela aplicação Keychain Access e atualizando a confiança do teu certificado para "Always Trust."

431 Campos do Cabeçalho da Requisição Muito Grandes

Quando o servidor ou servidor de websocket recebe um cabeçalho de HTTP grande, a requisição será largada e o seguinte aviso será exibido.

Server responded with status code 431. See https://vite.dev/guide/troubleshooting.html#_431-request-header-fields-too-large.

(Tradução) O servidor respondeu com o código de estado 431. Consulte https://pt.vite.dev/guide/troubleshooting.html#_campos-do-cabeçalho-da-requisição-muito-grandes.

Isto porque a Node.js limita o tamanho do cabeçalho da requisição para mitigar o CVE-2018-12121.

Para evitar isto, tente reduzir o tamanho do cabeçalho da tua requisição. Por exemplo, se o cookie for longo, elimine-o. Ou podes utilizar a --max-http-header-size para mudar o tamanho máximo do cabeçalho.

Substituição de Módulo Instantânea

A Vite Deteta uma Mudança de Ficheiro mas a HMR não está a Funcionar

Tu talvez estejas importando um ficheiro com uma caixa diferente. Por exemplo, src/foo.js existe e src/bar.js contém:

import './Foo.js' // deveria ser './foo.js'

Problema relacionado: #964

A Vite não Deteta uma Mudança de Ficheiro

Se estiveres executando a Vite com o WSL2, a Vite não consegue observar mudanças de ficheiro em algumas condições. Consulte a opção server.watch.

Um Recarregamento Completo Acontece no Lugar da Substituição de Módulo Instantânea

Se a substituição de módulo instantânea não for manipulada pela Vite ou por uma extensão, um recarregamento completo acontecerá uma vez que é a única maneira de atualizar o estado.

Se a substituição de módulo instantânea for manipulada mas está dentro duma dependência circular, um recarregamento completo também acontece para recuperar a ordem de execução. Para resolver isto, tente quebrar o laço de repetição. Nós podemos executar vite --debug hmr para registar o remendo de dependência circular se uma mudança de ficheiro o acionar.

Construção

O Ficheiro Construído não Funciona por Causa do Erro de CORS

Se o ficheiro HTML de saída foi aberto com o protocolo file, os programas (ou scripts se preferires) não executarão com o seguinte erro.

Access to script at 'file:///foo/bar.js' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.

(Tradução) O acesso ao programa em 'file:///foo/bar.js' a partir da origem 'null' foi bloqueada pela política de CORS: As requisições de origem cruzadas apenas são suportadas para os esquemas de protocolo: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///foo/bar.js. (Reason: CORS request not http).

(Tradução) Requisição de Origem Cruzada Bloqueada: A Mesma Política de Origem desautoriza a leitura do recurso em file:///foo/bar.js. (Motivo: Requisição de CORS não é de http).

Consulte o Motivo: Requisição de CORS não é HTTP - HTTP | MDN para obter mais informações a respeito do por quê isto acontece.

Tu precisarás acessar o ficheiro com o protocolo de http. A maneira mais fácil de alcançar isto é executar o npx vite preview.

Dependências Otimizadas

Dependências pré-empacotadas desatualizadas quando ligamos ao pacote local

A chave de has usada para invalidar dependências otimizadas depende do conteúdo de fecho do pacote, os remendos aplicados às dependências, e as opções no ficheiro de configuração da Vite que afetam o empacotamento dos módulos da node. Isto significa que a Vite detetará quando uma dependência for sobreposta usando uma funcionalidade como sobreposições de npm, e re-empacota as tuas dependências na próxima inicialização do servidor. A Vite não invalidará as dependências quando usas uma funcionalidade com o ligação de npm. No caso quando ligas ou desligas uma dependência, precisarás de forçar a re-otimização na próxima inicialização do servidor usando vite --force. Nós recomendamos usar as sobreposições, qua agora são suportadas por todos os gestores de pacotes (consulte também as sobreposições de pnpm e as resoluções de yarn).

Problemas de Desempenho

Se sofreres quaisquer problemas de desempenho de aplicação resultando em tempos de carregamento lentos, podes iniciar o inspetor de Node.js embutido com o teu servidor de desenvolvimento da Vite ou quando construíres a tua aplicação para criar o perfil da CPU:

servidor de desenvolvimento

vite --profile --open

construção

vite build --profile

Servidor de Desenvolvimento da Vite

Uma vez que a tua aplicação estiver aberta no navegador, apenas aguarde a conclusão do carregamento dela e depois siga para o terminal e pressione a tecla p (interromperá o inspetor da Node.js) depois pressione a tecla q para interromper o servidor de desenvolvimento.

O inspetor da Node.js gerará o ficheiro vite-profile-0.cpuprofile na pasta de raiz, siga para https://www.speedscope.app/, e carregue o perfil da CPU usando o botão BROWSE para inspecionar o resultado.

Nós podemos instalar vite-plugin-inspect, que permite-nos inspecionar o estado intermediário das extensões da Vite e também pode ajudar-nos a identificar quais extensões ou intermediários são congestionamentos nas nossas aplicações. A extensão pode ser usada em ambos modos de desenvolvimento e construção. Consulte o ficheiro leia-me por mais detalhes.

Outros

Módulo Exposto para Compatibilidade de Navegador

Quando usares um módulo de Node.js no navegador, a Vite produzirá o seguinte aviso.

Module "fs" has been externalized for browser compatibility. Cannot access "fs.readFile" in client code.

(Tradução) O módulo "fs" foi exposto para compatibilidade de navegador. Não podes acessar "fs.readFile" no código do cliente.

Isto porque a Vite não faz automaticamente o "polyfill" de módulos da Node.js.

Nós recomendamos evitar módulos de Node.js para o código do navegador para reduzir o tamanho do pacote, embora possas adicionar os "polyfill" manualmente. Se o módulo é importado a partir de uma biblioteca de terceiro (que destina-se a ser usada no navegador), é aconselhado reportar o problema para a respetiva biblioteca.

Ocorre Erro de Sintaxe / Erro de Tipo

A Vite não consegui manipular e não suporta o código que só executa no modo não restrito (modo desleixado). Isto porque a Vite utiliza Módulo de ECMAScript e sempre é modo restrito dentro do Módulo de ECMAScript.

Por exemplo, podes ver estes erros.

[ERROR] With statements cannot be used with the "esm" output format due to strict mode

(Tradução) [ERRO] a expressão with não pode ser utilizada com o formato de saída "esm" por causa do modo estrito

TypeError: Cannot create property 'foo' on boolean 'false'

(Tradução) Erro de Tipo: Não possível criar a propriedade 'foo' sobre o booleano 'false'

Se estes códigos são utilizados dentro de dependências, poderias utilizar patch-package (ou yarn patch ou pnpm patch) por uma escotilha de saída.

Extensões de Navegador

Algumas extensões de navegador (como bloqueadores de anúncios) podem impedir o cliente da Vite de enviar requisições para o servidor de desenvolvimento da Vite. Tu podes ver um ecrã branco sem erros registados neste caso. Tente desativar as extensões se tiveres este problema.

Ligações de Condução Transversal no Windows

Se existir ligações de condução transversal no teu projeto no Windows, a Vite talvez não funcione.

Os exemplos de ligações de condução transversal são:

• Uma unidade virtual ligada à uma pasta pelo comando subst.
• Uma ligação simbólica ou junção à uma unidade diferente pelo comando mklink (por exemplo, yarn global cache).

Questão relacionada: #10802.