Por que npm di "Failed to replace env in config: ${NPM_TOKEN}"?

Un ficheiro .npmrc referencia a variable de contorno NPM_TOKEN pero non está definida na túa shell, así que npm ou yarn non poden expandila e abortan o comando.

Onde busca npm os ficheiros .npmrc?

Nesta orde: o cartafol do proxecto, logo o teu directorio de usuario (~/.npmrc), logo o prefixo global e por último a configuración interna de npm. Os valores combínanse e gaña o ficheiro máis próximo, así que unha entrada obsoleta no teu .npmrc de usuario pode romper todos os proxectos.

Por que só falla en CI?

O .npmrc referencia ${NPM_TOKEN} pero o traballo de CI nunca recibiu ese segredo no seu contorno. Exponno como variable de contorno no paso que executa a instalación (por exemplo NPM_TOKEN: ${{ secrets.NPM_TOKEN }} en GitHub Actions).

Xabier Lameiro · 2023-01-03

Posible solución para NPM - Failed to replace env in config: ${NPM_TOKEN}

Q: Como se arranxa "Failed to replace env in config"?

Define a variable que falta (export NPM_TOKEN=o_teu_token) ou localiza o .npmrc que a referencia — na raíz do proxecto ou no teu cartafol de usuario — e elimina a entrada obsoleta. Executar a instalación con --verbose mostra que ficheiros .npmrc se están a ler.

Resposta rápida

npm ou yarn atoparon un ficheiro .npmrc que referencia unha variable de contorno (NPM_TOKEN) que non está definida na túa shell, así que non poden expandila. Exporta a variable (export NPM_TOKEN=o_teu_token) ou localiza o .npmrc que a referencia — na raíz do proxecto ou no teu cartafol de usuario — e elimina a entrada obsoleta. Executa a instalación con --verbose para ver exactamente que ficheiros .npmrc se están a ler.

O propio texto do erro dío: Failed to replace env in config: ${NPM_TOKEN}. npm está avisándote de que tentou substituír un marcador ${...} e non había nada co que enchelo.

Por que pasa

Para instalar un paquete privado do rexistro de GitHub apuntas npm a ese rexistro e dáslle un token. O token vive nunha variable de contorno para que nunca acabe no repositorio, e o .npmrc referéncialo polo seu nome:

.npmrc

@xabierlameiro:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

Cando executas npm install ou yarn, npm le ese ficheiro e expande cada ${VAR} contra o teu contorno actual. Se NPM_TOKEN non está definida nesa shell, non pode substituír o marcador e aborta: ese é o erro exacto.

Os ficheiros .npmrc que npm le de verdade

Esta é a parte que converte un arranxo dun minuto nun de dúas horas. npm non le un único .npmrc; combina varios, e gaña o máis próximo. Por orde de precedencia:

Proxecto: ./.npmrc
Usuario: ~/.npmrc (en Windows, C:\Users\<ti>\.npmrc)
Global: $PREFIX/etc/npmrc
Configuración interna de npm

Así que unha liña que engadiches hai meses ao teu .npmrc de usuario aplícase a todos os proxectos que instalas, mesmo os que non teñen nin idea de que é NPM_TOKEN. Esa é a razón habitual de que o erro apareza nun repo que nunca configuraches para o rexistro de GitHub.

Causas habituais, ordenadas

A variable non está realmente definida na shell desde a que lanzaches o comando.
O .npmrc está no teu cartafol de usuario, non no proxecto, e cólase en instalacións que non teñen nada que ver. Este foi o meu caso: gardárao en C:\Users\xabierlameiro\.npmrc, e todos os proxectos herdaban a referencia a ${NPM_TOKEN}.
A variable está definida nunha aplicación gráfica ou noutra pestana de terminal que non herdou o export.
En CI, o segredo existe pero nunca se expuxo ao contorno do paso.

Como o arranxei

Primeiro lancei a instalación en modo verbose para ver que ficheiros estaba a ler npm:

yarn install --verbose

O log lista as rutas onde busca o .npmrc, e aí vin que estaba collendo a configuración do meu cartafol de usuario. Elimineino do cartafol de usuario e volvino a crear na raíz do proxecto, e o erro desapareceu.

Se en cambio queres o token dispoñible en todas partes, defínea en vez de quitar a referencia:

export NPM_TOKEN=o_teu_token   # macOS / Linux
setx NPM_TOKEN o_teu_token     # Windows, só shells novas

npm config ls -l imprime a configuración combinada completa, que é a forma máis rápida de confirmar se o token se colleu.

Como arranxalo en CI

O sitio onde máis morde isto é a integración continua, porque o runner é unha máquina nova sen ningún dos teus exports locais. A solución é entregar o segredo ao paso como variable de contorno, co mesmo nome NPM_TOKEN que espera o .npmrc. En GitHub Actions:

workflow.yml

- name: Install dependencies
  env:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
  run: npm install --legacy-peer-deps

Se xeras o .npmrc no runner en vez de subilo ao repo, escribe a liña de autenticación directamente no ficheiro de usuario antes de instalar:

echo "//npm.pkg.github.com/:_authToken=${NPM_TOKEN}" >> ~/.npmrc
echo "@o-teu-scope:registry=https://npm.pkg.github.com/" >> ~/.npmrc

A idea é a mesma en calquera provedor de CI: a referencia do .npmrc e a variable de contorno teñen que coincidir no nome, e o valor ten que chegar ao proceso que executa a instalación.

Mantén o token fóra de git

Unha última cousa, porque é un fallo que vexo a miúdo. O .npmrc que referencia ${NPM_TOKEN} pódese subir sen problema: só contén o nome da variable, non o seu valor. O que nunca debe chegar a git é un .npmrc co token literal pegado (_authToken=ghp_...). Se o fixeches, o token queda comprometido no momento en que se sobe — revócao e rótao en GitHub, non abonda con borrar o ficheiro, porque o historial de git consérvao. A regra: un .npmrc que só referencia variables de contorno pódese subir e ata axuda aos teus compañeiros; un con segredos reais vai ao .gitignore e, mellor aínda, non debería existir.

Xa pase en local ou nun pipeline, a pregunta é sempre a mesma: ten a shell que executa npm realmente NPM_TOKEN, e está a ler o .npmrc que cres? Responde a esas dúas e o erro desaparece.