Você está tentando usar Pacotes Privados no projeto da sua empresa, mas está preso na configuração do .npmrc?

Por que você ainda recebe 404 Not Found mesmo depois de configurar o Token?

Quando a empresa tem várias equipes e vários pacotes (por exemplo, @frontend, @backend), como você gerencia o .npmrc com elegância?

Derrubando os dois mitos do .npmrc

Para entender o .npmrc, você precisa primeiro entender como ele funciona.

Simplesmente, sua lógica central são apenas duas coisas: Mapeamento de Escopo (Scope Mapping) e Autenticação.

1. Mapeamento de Escopo (Scope Mapping)

Isso diz ao npm: Quando você vir um pacote começando com @company, não vá para o npmjs.org oficial, vá para o nosso GitLab Registry especificado.

@company:registry=https://gitlab.com/api/v4/groups/100/-/packages/npm/

2. Autenticação (Authentication)

Com o endereço, você também precisa de uma chave. A chave é o seu AuthToken.

Aqui está uma regra super crucial: A URL do Registry e o caminho do AuthToken devem “corresponder exatamente”.

# ✅ Correto: O caminho é exatamente o mesmo que o registry definido acima
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ Incorreto: Caminho incompatível, isso causará falha de permissão
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Muitas pessoas falham na configuração muitas vezes porque o caminho tem uma barra extra ou falta um nível.

Inferno de Dependências e Erros 404

A situação mais dolorosa é: Você instala o pacote A, que depende do pacote B (também privado), e então o npm cospe um 404 Not Found.

Por que isso acontece? Isso é porque quando o npm resolve dependências, se não houver uma relação correta, ele se perde.

Especialmente quando você tem dois Escopos diferentes (por exemplo, @team-a e @team-b) em diferentes Grupos do GitLab, o .npmrc torna-se extremamente complexo e difícil de manter. Além disso, diferentes Registries podem precisar de diferentes Tokens, apenas gerenciar essas variáveis de ambiente é exaustivo.

Existe uma maneira mais inteligente?

Solução Recomendada: Unified Download Group Registry e Independent Publish Project Registry

Por que fazer isso?

Configuração em Ação

Você pode copiar diretamente este modelo:

Lembre-se de entregar a tarefa de proteger o Token às variáveis de ambiente, absolutamente não codifique o Token no código!

# .npmrc
# @company scope usa registry de nível de grupo
# Todos os pacotes @company/* serão instalados a partir deste registry
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Configuração de autenticação do GitLab npm registry
# Usar token de autenticação comum do gitlab.com (cobre todas as solicitações de nível de grupo e projeto)
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# Usar registry do projeto para publicar pacotes
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# Outros pacotes públicos ainda vão para o registry oficial
registry=https://registry.npmjs.org/

Configure publishConfig no package.json para publicar o pacote no GitLab Project Registry correspondente.

{
  "name": "@company/my-package",
  "publishConfig": {
    "@company:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
  }
}

Conclusão

Através da estratégia de “Unified Download Group Registry” e “Independent Publish Project Registry”, podemos reduzir significativamente os custos de manutenção e tornar o fluxo de desenvolvimento mais suave.

Dominando essas lógicas, o GitLab NPM Registry será um assistente poderoso no processo de desenvolvimento da sua empresa!