Clique em 'Upload' e a ferramenta de desenvolvimento exibe uma linha vermelha: o tamanho do pacote principal excede o limite de 2MB. A versão não pode ser enviada e as solicitações ainda estão na fila.
Este artigo não aborda um manual completo de princípios, mas sim lista métodos para reduzir o pacote principal para menos de 2MB, ordenados por 'economia mais alta, alteração mais baixa'.
Primeiro, esclareça: o que exatamente o limite de 2MB bloqueia
O WeChat tem dois limites rígidos para o tamanho do pacote de código do Mini Program:
| Limitação | Limite |
|---|---|
| Pacote principal (incluindo app.js, páginas tabBar, recursos públicos etc.) | 2MB |
| Pacote secundário individual | 2MB |
| Todos os pacotes do Mini Program juntos | 20MB |
Observe que o 'tamanho' aqui refere-se ao tamanho do pacote de código após o upload, não apenas ao JS. Todos os arquivos que serão empacotados no diretório do projeto são contados: .js, .wxml, .wxss, ., fontes, áudio e — geralmente ocupando a maior parte — imagens.
Este é um limite rígido de 'não enviar versão se não conseguir comprimir', não 'otimizar um pouco'. Portanto, a primeira etapa não é agir, mas sim identificar onde o espaço está sendo gasto.
Passo 0: Veja o que está ocupando espaço no pacote principal
Na ferramenta de desenvolvimento do WeChat, 'Detalhes → Informações Básicas' no canto superior direito mostra o tamanho total do pacote de código local; mais detalhado está na barra de ferramentas 'Análise de Dependência de Código', que lista o tamanho por arquivo e marca quais arquivos não são referenciados por nenhuma página.
A maioria dos projetos, ao ver esta tabela, descobre a mesma coisa: recursos estáticos como imagens e fontes são muito maiores que o código de negócios. O JS pode ter centenas de KB com dezenas de milhares de linhas, enquanto uma imagem de banner não processada pode ter centenas de KB, e um diretório images/ pode facilmente comer metade do pacote principal.
Abaixo estão listados por ordem de benefício, do maior para o menor.
Método 1: Excluir arquivos que não são usados
O mais fácil e frequentemente ignorado.
- Arquivos marcados como não referenciados na 'Análise de Dependência de Código': ícones antigos de revisões históricas, páginas obsoletas, imagens de teste, exclua diretamente.
- Arquivos que não devem entrar no pacote: designs, README,
.psd, materiais originais, dados de Mock. Mova-os para fora do diretório do projeto; se não puder, usepackOptions.ignorenoproject.config.para excluir:
{
"packOptions": {
"ignore": [
{ "type": "folder", "value": "design" },
{ "type": "suffix", "value": ".psd" }
]
}
}
- Importação em massa de bibliotecas de componentes: é comum ter um 'gorduro invisível' ao incluir toda a biblioteca de UI, embora apenas três componentes sejam usados. Altere para importação sob demanda, mantendo apenas os diretórios de componentes utilizados.
Método 2: Subpacotes — Mova páginas não da primeira tela para fora do pacote principal
Esta é a solução oficial. Mantenha apenas a página de inicialização, páginas tabBar e o código público real necessário no pacote principal; divida as outras páginas por negócio em subpacotes:
{
"pages": ["pages/index/index", "pages/mine/mine"],
"subPackages": [
{ "root": "packageOrder", "pages": ["list/list", "detail/detail"] },
{ "root": "packageActivity", "pages": ["index/index"] }
],
"preloadRule": {
"pages/index/index": { "network": "all", "packages": ["packageOrder"] }
}
}
Pontos principais:
- Recursos seguem a página: as imagens e componentes usados pelas páginas de subpacotes devem ser colocados nos diretórios de subpacotes. Se colocados na pasta pública
images/no pacote principal, mesmo que o subpacote seja dividido, o volume ainda é contado no pacote principal. preloadRulepré-download de subpacotes: ao entrar na página inicial, baixe os subpacotes provavelmente usados a seguir, de modo que o usuário não sinta quase nenhum atraso ao clicar neles.- Subpacote Independente (
"independent": true): adequado para páginas de atividade, páginas de aterrissagem, etc., que podem ser abertas independentemente do pacote principal sem depender dele na inicialização. - Assincronia de subpacotes: ao fazer referência a componentes ou JS entre subpacotes, você pode usar componentes de espaço reservado e
require.asyncpara evitar trazer o código de volta ao pacote principal apenas para 'compartilhar'.
O custo dos subpacotes é alterar a estrutura do diretório e os caminhos de navegação. A refatoração de projetos antigos pode envolver um trabalho considerável, o que é por que vale a pena fazer o passo a seguir primeiro — muitas vezes, após fazer isso, o pacote principal já volta para menos de 2MB.
Método 3: Comprimir imagens (mudança mínima, benefício mais direto)
Imagens são a parte mais propensa a ficar 'gorda' no pacote principal. PNGs exportados por designers podem conter blocos de dados extras, e JPGs podem usar parâmetros de qualidade altos. Esses bytes não são visíveis pelos usuários, mas cada um conta para os 2MB.
Quais imagens devem permanecer no pacote
Nem todas as imagens podem ser movidas para CDN:
- Ícones da barra de abas:
iconPath/selectedIconPathsó aceitam caminhos locais, não imagens de rede. - Página de inicialização, Logo da primeira tela, Imagens de espaço reservado de fallback: precisam ser exibidas mesmo em redes fracas ou offline.
- Ícones pequenos que aparecem com frequência: não é prático fazer uma solicitação de rede a cada vez.
Essas imagens só podem permanecer no pacote, então o único método é torná-las menores.
Evite um buraco comum: imagens de fundo no wxss
Usar background-image no .wxss para referenciar imagens locais não funciona em dispositivos reais. A solução comum é convertê-las em base64 inline. No entanto, a codificação base64 fará o volume inflar cerca de um terço, e ela fica escondida no arquivo de estilo, não sendo muito óbvia na análise de dependência. Se puder ser alterada para um componente <image> ou imagem de rede, não faça inline; se não puder, comprima a imagem original antes de converter.
Use ImgZilla para compactação no local de todo o diretório de recursos
O que mais teme ao fazer Mini Programs é ter que voltar e alterar caminhos após comprimir as imagens — no wxml, no wxss, nas configurações JS, nas configurações tabBar, há referências a /images/xxx.png em todo lugar. Muitas ferramentas de compressão salvam como xxx-min.png ou exigem que você exporte para outra pasta, exigindo troca manual e verificação se algo foi perdido.
ImgZilla é uma ferramenta de compressão de imagens para macOS que usa compactação no local:
- Nome do arquivo, caminho e formato permanecem inalterados.
icon-home.pngainda éicon-home.png, nenhuma linha de código precisa ser alterada. - Basta arrastar todo o diretório. Ele varre recursivamente todos os subdiretórios, pulando automaticamente arquivos ocultos e
node_modules. Arrasteimages/,static/ou até todo o diretório do projeto; depois, veja a mudança no tamanho do pacote na ferramenta de desenvolvimento. - A imagem original é movida para a lixeira por padrão; se não gostar, clique com o botão direito em 'Restaurar' para reverter. Se o projeto estiver no Git, isso oferece uma camada extra de segurança.
- Executa localmente, sem upload para a rede. Os materiais de projetos corporativos não saem do seu computador, sem as limitações de quantidade de imagens ou tamanho por arquivo de sites de compressão online.
Em termos de qualidade, o tratamento é diferente para cada formato. Aqui está o esclarecimento:
- PNG: usa oxipng para compressão sem perda, nenhum pixel é alterado. Muitos ícones e cortes em Mini Programs são PNG, então pode comprimir com segurança.
- SVG: limpa marcas redundantes, também sem perda.
- JPG / WebP / GIF etc.: são recodificações com perdas, com parâmetros ajustados para o intervalo 'visualmente sem perda' — difícil de notar a diferença a olho nu. Não confie apenas na confiança; a janela de comparação integrada (
⌘D) permite divisão esquerda/direita e ampliação para pixel real para comparar de imagem em imagem.
Dois pontos adicionais:
- Não força compressão se já estiver no limite: arquivos com taxa de compressão inferior a 0,4% são marcados como 'já mínimo', mantidos como estão, para não sujar a imagem apenas para parecer um número melhor. Portanto, se suas imagens já foram otimizadas com seriedade, esta etapa pode economizar pouco — isso é normal e indica que deve-se mudar para subpacotes.
- Não altera formato nem resolução. PNG continua PNG, tamanho inalterado. Se você quiser mudar para WebP ou reduzir imagens de 3x para 2x, é outra questão que precisa de tratamento separado.
Quanto se pode economizar depende de como as imagens foram exportadas originalmente; não daremos uma porcentagem genérica. Como referência, fizemos testes públicos em duas ocasiões: um lote de JPG já comprimido durante o processo de entrada de site ainda economizou 46,8% ao comprimir novamente; um lote de JPG direto da câmera economizou 76,8% (veja a série 'Testes reais ImgZilla'). As imagens em Mini Programs geralmente são exportadas diretamente de ferramentas de design, geralmente não foram seriamente comprimidas, então vale a pena rodar uma vez para ver.
ImgZilla atualmente tem apenas versão para macOS (macOS 12.3 ou superior), disponível na Mac App Store, com 10 imagens gratuitas por dia. Estudantes que usam Windows podem aplicar a mesma lógica deste tópico, trocando por uma ferramenta que também 'mantenha o nome do arquivo original'.
Método 4: Mova imagens grandes para CDN
Após comprimir, imagens que ainda são muito grandes — como banners de atividades, imagens longas de páginas de detalhes, grandes imagens de produtos — não são adequadas para ficar no pacote. Faça upload para armazenamento de objetos ou CDN, troque por endereços de rede no código e o pacote principal se sentirá imediatamente mais leve.
Mas isso não é gratuito:
- A primeira carga precisa passar pela rede; em redes fracas haverá um período em branco, idealmente combinado com imagens de espaço reservado ou tela de esqueleto.
- É necessário manter um processo de upload, cache e atualização.
- CDN cobrado por tráfego. Cada vez que uma imagem é carregada, você paga. A taxa de tráfego é equivalente a 'tamanho da imagem × número de acessos'. Portanto, antes de mover para CDN, também vale a pena comprimir as imagens primeiro — comprimir uma vez economiza tráfego a cada acesso subsequente.
Método 5: Finalização no nível do código
Com imagens e estrutura tratados, o espaço restante pode ser recuperado do código:
- Na ferramenta de desenvolvimento, 'Detalhes → Configurações Locais', marque para compressão de scripts, estilos e WXML ao fazer upload.
- No
app., ative"lazyCodeLoading": "requiredComponents"(injeção sob demanda). Ela melhora principalmente a velocidade de inicialização em vez do tamanho do pacote, mas como estamos otimizando desempenho, ative também. - Verifique
miniprogram_npm: verifique se os pacotes npm construídos têm importação de pacote inteiro com apenas uma ou duas funções usadas. - Dados estáticos grandes escritos diretamente no JS (listas de cidades, tabelas de configuração) considere mudar para entrega via API.
Uma tabela resumo
| Método | Quanto economizar | Quanto alterar | Ordem recomendada |
|---|---|---|---|
| Excluir arquivos não usados | Dependente do histórico do projeto | Pouco | 1 |
| Compactação no local de imagens | Mais imagens, exportação mais casual = mais economia | Quase zero, caminhos inalterados | 2 |
| Subpacotes | Pode ser muito | Estrutura de diretórios e rotas precisam mudar | 3 |
| Mover imagens grandes para CDN | Muito | Precisa alterar referências, manter processo de upload | 4 |
| Compressão de código e importação sob demanda | Pouco | Depende | 5 |
A lógica da ordem é simples: faça primeiro alterações pequenas, depois alterações grandes. Excluir arquivos e comprimir imagens quase não tocam no código de negócio; após fazer isso, veja quanto ainda falta no pacote principal — se já estiver abaixo de 2MB, a versão de hoje pode ser enviada; se não for suficiente, então mova para subpacotes e CDN, com uma ideia clara.
O excesso de tamanho do pacote principal muitas vezes acontece no momento mais tenso antes do lançamento. Coloque a compressão de imagens no fluxo diário — comprima antes de adicionar uma nova imagem — e da próxima vez, não precisará se preocupar com aquela linha vermelha na data limite.