Como Ativar HTTPS Local para Desenvolvimento

A maioria dos desenvolvedores frontend assume que precisa de HTTPS rodando localmente para usar APIs do navegador como service workers ou geolocalização. Na verdade, isso é um equívoco — os navegadores já tratam localhost como um contexto seguro, então essas APIs funcionam perfeitamente via HTTP simples. Mas existem situações reais onde você genuinamente precisa de HTTPS local: testar URLs de callback OAuth, trabalhar com cookies em um ambiente semelhante ao de produção, desenvolver com um hostname personalizado, ou replicar o comportamento de produção com precisão. Este artigo mostra como configurar isso de forma limpa.

Quando Você Realmente Precisa de HTTPS Local

Antes de buscar um certificado, pergunte-se se você realmente precisa de um. http://localhost é tratado como uma origem potencialmente confiável por todos os principais navegadores. Service workers, acesso à câmera e a maioria das APIs de contexto seguro funcionam sem nenhuma configuração HTTPS. Você pode confirmar esse comportamento nos dados de compatibilidade do navegador em webstatus.dev.

Você ainda pode querer HTTPS local real quando:

• Está testando comportamento de cookies em condições que correspondem à produção, especialmente com cookies Secure em hostnames que não sejam localhost
• Está testando fluxos OAuth ou OIDC com URLs de callback que devem corresponder a uma origem HTTPS registrada
• Está desenvolvendo com um hostname personalizado como app.localhost em vez de localhost
• Precisa testar em um dispositivo móvel na mesma rede
• Seu frontend e backend rodam localmente e devem se comunicar via HTTPS para replicar o comportamento de produção

Se nenhum desses casos se aplica, pule a configuração e mantenha as coisas simples.

Por Que Certificados Autoassinados Não Funcionam Bem

O primeiro instinto óbvio é gerar um certificado autoassinado. O problema: navegadores não confiam em certificados a menos que sejam assinados por uma autoridade certificadora conhecida. Um certificado autoassinado dispara o aviso “Sua conexão não é privada”, e você terá que clicar nele toda vez — ou desabilitar completamente a verificação de certificados, o que cria maus hábitos.

A abordagem correta é criar uma autoridade certificadora local em que seu sistema e navegadores confiem, e então emitir certificados assinados por essa CA. É exatamente isso que o mkcert faz.

Configurando Certificados Locais Confiáveis com mkcert

mkcert é uma ferramenta de configuração zero que cria uma CA local, registra-a no armazenamento de confiança do seu sistema e emite certificados assinados por ela. Os navegadores confiam nesses certificados sem avisos.

Passo 1: Instalar o mkcert

No macOS:

brew install mkcert
brew install nss  # required for Firefox

No Linux, use seu gerenciador de pacotes ou siga o guia de instalação do mkcert. No Windows, use Chocolatey ou Scoop.

Passo 2: Registrar a CA local

mkcert -install

Isso cria uma CA raiz e a adiciona ao armazenamento de confiança do seu sistema. Você só precisa fazer isso uma vez por máquina.

Passo 3: Gerar um certificado para seu hostname

mkcert localhost
# ou para um hostname personalizado:
mkcert app.localhost

Isso produz dois arquivos: um certificado (.pem) e uma chave privada (-key.pem). Mantenha-os fora do controle de versão — adicione-os ao seu .gitignore.

Configurando Seu Servidor de Desenvolvimento para Usar HTTPS

Como você passa o certificado para seu servidor de desenvolvimento depende das suas ferramentas.

Vite — o caminho mais simples, usando vite-plugin-mkcert:

import mkcert from 'vite-plugin-mkcert'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [mkcert()]
})

O plugin cuida da geração do certificado e configuração do servidor automaticamente.

Vite (manual):

import fs from 'fs'
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('./localhost-key.pem'),
      cert: fs.readFileSync('./localhost.pem'),
    }
  }
})

Next.js — use a flag next dev --experimental-https disponível em versões recentes, ou configure manualmente um servidor HTTPS Node.js personalizado usando os mesmos arquivos de certificado.

Node.js (qualquer framework):

const https = require('https')
const fs = require('fs')

https.createServer({
  key: fs.readFileSync('localhost-key.pem'),
  cert: fs.readFileSync('localhost.pem'),
}, app).listen(3000)

Importante: Nunca compartilhe ou faça commit do arquivo rootCA-key.pem que o mkcert gera. Se alguém obtiver esse arquivo, pode emitir certificados confiáveis para qualquer domínio na sua máquina. Execute mkcert -CAROOT para descobrir onde ele está armazenado.

Uma Nota de Segurança sobre Node.js

Se seu backend local faz requisições HTTPS para outros serviços locais, o Node.js não confiará automaticamente na sua CA do mkcert — ele usa sua própria lista integrada de autoridades confiáveis em vez do armazenamento de confiança do sistema. Corrija isso definindo uma variável de ambiente:

export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

Adicione isso ao seu perfil de shell (.bashrc, .zshrc, etc.) para que persista entre as sessões.

Conclusão

Habilitar HTTPS localmente não é algo que todo projeto precisa — mas quando você precisa, um certificado autoassinado não será suficiente. O mkcert fornece certificados localhost devidamente confiáveis em minutos, sem avisos do navegador ou soluções alternativas. Configure uma vez, aponte seu servidor de desenvolvimento para os arquivos gerados, e seu ambiente local se comportará exatamente como produção.

Perguntas Frequentes

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.