Vite: Corrigir "Failed to resolve import" (aliases de caminho)

Você acabou de configurar aliases de caminho no seu projeto Vite, substituindo aquelas importações desajeitadas ../../../components por caminhos limpos @/components. Mas agora o Vite lança um erro frustrante: “Failed to resolve import”. Isso acontece porque o Vite e o TypeScript lidam com a resolução de módulos de forma diferente, e corrigi-lo requer sincronizar duas configurações separadas.

Este guia mostra exatamente como corrigir erros de aliases de caminho do Vite usando dois métodos comprovados: configuração manual para controle total, ou o plugin automatizado vite-tsconfig-paths para simplicidade.

O Erro “Failed to resolve import” no Vite

O erro Vite Failed to resolve import aparece quando seu bundler não consegue localizar módulos usando seus aliases de caminho personalizados. Você verá variações como:

• [vite] Internal server error: Failed to resolve import "@/components/Header"
• Cannot find module '@/utils' or its corresponding type declarations
• Erro TypeScript TS2307 na sua IDE

Esses erros bloqueiam seu servidor de desenvolvimento, quebram o hot module replacement e impedem builds bem-sucedidos—transformando o que deveria ser um aumento de produtividade em um obstáculo.

Entendendo Por Que os Aliases de Caminho do Vite Falham

O Problema das Duas Configurações

O Vite usa Rollup para bundling, enquanto o TypeScript lida com verificação de tipos separadamente. Cada ferramenta precisa de sua própria configuração:

• Vite precisa de resolve.alias em vite.config.ts para bundling de módulos
• TypeScript precisa de paths em tsconfig.json para verificação de tipos e suporte da IDE

Quando essas configurações não correspondem, você obtém erros de resolução de importação. O Vite pode entender @/components, mas o TypeScript não—ou vice-versa.

Gatilhos Comuns para Erros de Importação

Três problemas causam a maioria dos erros de resolve alias do Vite:

1. Tipos Node.js ausentes: Usar path.resolve() sem @types/node
2. Incompatibilidades de sintaxe: Vite usa notação de objeto enquanto TypeScript usa padrões de array
3. Conflitos de formato de módulo: Usar variáveis específicas de CommonJS como __dirname em projetos ESM

Método 1: Configuração Manual para Aliases TypeScript do Vite

Passo 1: Configurar vite.config.ts

Primeiro, instale os tipos Node.js necessários:

npm install -D @types/node

Depois atualize sua configuração do Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
      '@components': fileURLToPath(new URL('./src/components', import.meta.url)),
      '@utils': fileURLToPath(new URL('./src/utils', import.meta.url))
    }
  }
})

Para projetos CommonJS, você pode usar path.resolve() com __dirname:

// vite.config.ts (CommonJS)
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@utils': path.resolve(__dirname, './src/utils')
    }
  }
})

Passo 2: Atualizar tsconfig.json

Configure o TypeScript para reconhecer os mesmos aliases:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

Note a diferença de sintaxe: Vite usa '@components' enquanto TypeScript usa "@components/*" com valores em array.

Verificando Sua Configuração

Teste sua configuração com uma importação:

// Antes: import Button from '../../../components/Button'
import Button from '@components/Button'

Sua IDE deve fornecer sugestões de autocompletar, e npm run dev deve iniciar sem erros.

Método 2: Configuração Automatizada com vite-tsconfig-paths

Instalação e Configuração Básica

O plugin vite-tsconfig-paths sincroniza automaticamente seus paths do TypeScript com o Vite:

npm install -D vite-tsconfig-paths

Atualize sua configuração do Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [react(), tsconfigPaths()]
})

É isso. O plugin lê os paths do seu tsconfig.json e configura o Vite automaticamente.

Benefícios Sobre a Configuração Manual

• Fonte única de verdade: Atualize apenas o tsconfig.json
• Sem erros de sincronização: Aliases sempre correspondem
• Arquivos de configuração mais limpos: Menos código boilerplate
• Suporte a monorepo: Lida com configurações de workspace complexas

Solucionando Erros de Resolve Alias do Vite

Projetos JavaScript Sem TypeScript

Para projetos JavaScript, crie um jsconfig.json em vez disso:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

O plugin vite-tsconfig-paths funciona com jsconfig.json também.

Monorepo e Cenários Avançados

Em monorepos, certifique-se de que seus paths são relativos à raiz do workspace:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["packages/app/src/*"],
      "@shared/*": ["packages/shared/src/*"]
    }
  }
}

Para usuários Windows, sempre use barras normais (/) nas configurações de caminho—tanto Vite quanto TypeScript as normalizam corretamente.

Discrepâncias entre Build e Desenvolvimento

Se os aliases funcionam em desenvolvimento mas falham durante o build:

1. Verifique problemas de sensibilidade a maiúsculas/minúsculas (especialmente no Linux/macOS)
2. Certifique-se de que baseUrl está configurado corretamente
3. Verifique se todos os caminhos com alias existem na saída do build
4. Verifique se sua ferramenta de build preserva a configuração de alias

Referência Rápida: Manual vs vite-tsconfig-paths

Conclusão

Corrigir erros de Vite Failed to resolve import se resume a alinhar a resolução de módulos entre Vite e TypeScript. O método manual oferece controle preciso sobre ambas as configurações, enquanto vite-tsconfig-paths elimina completamente as dores de cabeça de sincronização.

Para a maioria dos projetos, comece com vite-tsconfig-paths—é mais simples e previne divergência de configuração. Mude para configuração manual apenas quando precisar de estratégias de aliasing diferentes entre desenvolvimento e produção, ou ao trabalhar com configurações de build incomuns que requerem lógica de resolução personalizada.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.