Êtes-vous bloqué sur la configuration .npmrc parce que le projet de votre entreprise doit utiliser des Private Packages ?

Pourquoi cela affiche-t-il toujours 404 Not Found alors que le Token est configuré ?

Quand une entreprise a plusieurs équipes et plusieurs paquets (par exemple @frontend, @backend), comment gérer élégamment le .npmrc ?

Démystifier les deux mythes de .npmrc

Pour comprendre .npmrc, vous devez d’abord comprendre comment il fonctionne.

Simplement dit, sa logique centrale se résume à deux choses : Correspondance de Portée (Scope Mapping) et Authentification (Authentication).

1. Correspondance de Portée (Scope Mapping)

Cela dit à npm : Quand tu vois un paquet commençant par @company, ne le cherche pas sur le npmjs.org officiel, mais va sur notre GitLab Registry spécifié.

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

2. Authentification (Authentication)

Avec l’adresse, vous avez aussi besoin d’une clé. La clé est votre AuthToken.

Voici une règle super critique : L’URL du Registry et le chemin de l’AuthToken doivent “correspondre exactement”.

# ✅ Correct : Le chemin est exactement le même que le registry défini ci-dessus
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ Incorrect : Le chemin ne correspond pas, ce qui causera un échec de permission
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Beaucoup de gens échouent souvent dans la configuration à cause d’un slash en trop ou d’un niveau manquant dans le chemin.

Enfer des Dépendances et Erreurs 404

La situation la plus casse-tête est : Vous installez le paquet A, qui dépend du paquet B (aussi privé), et ensuite npm recrache un 404 Not Found.

Pourquoi cela arrive-t-il ? C’est parce que npm se perd lors de la résolution des dépendances s’il n’y a pas de correspondance correcte.

Surtout quand vous avez deux Portées différentes (par exemple @team-a et @team-b) dans différents Groupes GitLab, .npmrc peut devenir extrêmement compliqué et difficile à maintenir. Couplé au fait que différents Registries peuvent nécessiter différents Tokens, gérer ces variables d’environnement suffit à vous rassasier.

Y a-t-il un moyen plus intelligent ?

Solution Recommandée : Group Registry de Téléchargement Unifié & Project Registry de Publication Indépendante

Pourquoi faire cela ?

Configuration en Action

Vous pouvez copier ce modèle directement :

Rappelez-vous de confier le travail de protection des Tokens aux variables d’environnement, ne codez jamais en dur les Tokens directement dans le code !

# .npmrc
# Token d'authentification de niveau domaine général (couvre toutes les demandes d'installation de niveau groupe et projet)
//gitlab.com/:_authToken=${GITLAB_NPM_TOKEN}

# Pour la publication : token d'authentification de niveau projet (npm publish nécessite une correspondance de chemin exacte)
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

# portée @company utilise le registry de niveau groupe
# Tous les paquets @company/* seront installés depuis ce registry
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Les autres paquets publics vont toujours à la bibliothèque officielle
registry=https://registry.npmjs.org/

Configurez publishConfig dans package.json pour publier le paquet dans le GitLab Project Registry correspondant.

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

Conclusion

Grâce à la stratégie de “Group Registry de Téléchargement Unifié” et “Project Registry de Publication Indépendante”, nous pouvons réduire considérablement les coûts de maintenance et rendre le processus de développement plus fluide.

En maîtrisant ces logiques, GitLab NPM Registry sera un allié puissant dans le processus de développement de votre entreprise !