Node.js en Windows — ¿Nativo o WSL2, cuál usar?

La primera pregunta al ejecutar Node.js en Windows: «¿Instalar en WSL2 Linux o nativo en Windows?» Ambos funcionan, pero el rendimiento, la compatibilidad de herramientas y la experiencia de depuración difieren radicalmente. Esta guía compara los dos entornos, ofrece una regla de decisión y explica ambas configuraciones.

Creo que la respuesta correcta en la mayoría de casos es WSL2, ya que la producción es Linux. En lugar de lidiar con diferencias de comportamiento entre entornos, desarrollar donde se despliega elimina una categoría entera de bugs.

Audiencia: desarrolladores que escriben JavaScript/TypeScript en Windows 11. Se asume que la configuración inicial de Windows está hecha.

Resumen

Regla general: la producción es Linux de todas formas. Desarrollar en WSL2 coincide con la producción. Sin una razón contraria de peso, opta por WSL2.

Requisitos previos

• Windows 11 22H2+
• WSL2 + Ubuntu 24.04 (configuración inicial de Windows)
• Windows Terminal (opcional — windows-terminal-setup)

1. Nativo vs WSL2 — diferencias fundamentales

Rendimiento

El ext4 de WSL2 aplasta a NTFS en el patrón de «muchas lecturas de archivos pequeños» que genera Node. Advertencia: montar archivos de Windows (/mnt/c/...) dentro de WSL2 es más lento que el nativo — véase §6.2.

Compatibilidad de herramientas

Depuración

2. Tabla de decisión

Elige WSL2 si

• La producción es Linux — Vercel / AWS / GCP / Heroku cubre el 99% de los casos
• Uso intensivo de módulos node-gyp — sharp, canvas, @tensorflow/tfjs-node
• Quieres un servidor de desarrollo rápido + HMR — el mayor diferenciador del día a día
• La CI ejecuta Ubuntu/Alpine — probar en Linux garantiza que la CI pase
• Colaboras con usuarios de Mac — entorno casi idéntico (POSIX)

Elige Windows nativo si

• Construyes aplicaciones de escritorio Electron — produciendo binarios para Windows
• Compilaciones Tauri en Windows — Rust + WebView2
• APIs exclusivas de Windows — COM, acceso al Registro
• Scripts de automatización simples — automatización del Bloc de notas, etc.
• VS Code Remote-WSL se siente demasiado lento en una máquina de bajas especificaciones

O usa ambos

Habitual: WSL2 para el trabajo, nativo para aplicaciones de escritorio secundarias. Sin conflicto — PATHs separados.

3. Configuración de Node.js en WSL2 (recomendado)

3.1 Entrar en WSL Ubuntu

wsl -d Ubuntu-24.04

3.2 mise para Node (recomendado)

# Instalar mise (gestor de versiones de lenguaje)
curl https://mise.run | sh
echo 'eval "$(/home/$USER/.local/bin/mise activate bash)"' >> ~/.bashrc
exec bash
 
# Instalar Node
mise use --global node@22
node --version    # v22.x

Más sobre mise: mac/dev-toolchain — funciona igual en Linux.

3.3 O nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
exec bash
nvm install --lts
nvm use --lts

3.4 O apt (paquete del sistema)

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

⚠️ apt hace incómodo el cambio de versión y requiere sudo. Prefiere mise o nvm.

3.5 pnpm, yarn

npm install -g pnpm yarn

3.6 Verificación

node --version    # v22.x
npm --version
pnpm --version
which node        # ~/.local/share/mise/installs/node/22/bin/node (con mise)

4. WSL2 + integración con VS Code

4.1 Extensión Remote-WSL

Extensiones de VS Code:

• WSL (ms-vscode-remote.remote-wsl)

Tras instalarla, paleta de comandos → WSL: Connect to WSL → elige Ubuntu.

O, desde dentro de WSL Ubuntu:

cd ~/projects/myapp
code .

VS Code se abre en Windows; el backend se ejecuta en WSL2.

4.2 Efecto

• node / npm / pnpm se ejecutan dentro de WSL2
• Los archivos viven en el ext4 de WSL2 (~/projects/myapp)
• El terminal es el bash de WSL2
• El depurador y las extensiones se ejecutan en el lado WSL2

No trabajes en el sistema de archivos de Windows (C:\) — el rendimiento se desploma.

5. Configuración de Node.js nativo en Windows

5.1 Instalación con winget

# LTS más reciente
winget install OpenJS.NodeJS.LTS
 
node --version    # v22.x

5.2 O fnm (gestor de versiones)

winget install Schniz.fnm
 
# Activar automáticamente desde el perfil de PowerShell
notepad $PROFILE
# Añade:
# fnm env --use-on-cd | Out-String | Invoke-Expression

Cambia automáticamente según .nvmrc / package.json#engines.node.

5.3 O NVM para Windows

winget install CoreyButler.NVMforWindows
 
nvm install lts
nvm use lts

nvm-windows es un proyecto separado del nvm Unix. Los comandos son similares.

5.4 Herramientas de compilación (para compilar módulos nativos)

Para compilar sharp / canvas / bcrypt, etc.:

winget install Microsoft.VisualStudio.2022.BuildTools

O:

npm install -g windows-build-tools  # obsoleto — prefiere Visual Studio Build Tools

5.5 Verificación

node --version
npm --version
pnpm --version

6. Problemas frecuentes

6.1 Ambos instalados → confusión sobre cuál se ejecuta

WSL2 tiene su propio node, Windows tiene el suyo — versiones distintas por terminal. Solución:

• Dentro de WSL bash, el Node de WSL (which node → ~/.local/share/mise/...)
• En PowerShell, el Node nativo (Get-Command node → C:\Program Files\nodejs\...)
• Fija el terminal predeterminado de VS Code (terminal.integrated.defaultProfile.windows: Ubuntu (WSL))

6.2 El montaje del sistema de archivos de Windows es lento

Trabajar desde /mnt/c/Users/me/projects/myapp en WSL2 → E/S entre 5 y 10 veces más lenta.

# ❌ Lento
cd /mnt/c/Users/me/projects/myapp
npm install
 
# ✅ Rápido
cp -r /mnt/c/Users/me/projects/myapp ~/projects/
cd ~/projects/myapp
npm install

Migra cualquier proyecto existente en carpeta de Windows a WSL2 una vez.

6.3 Finales de línea (CRLF vs LF)

Editar en WSL2 → hacer commit → abrir el mismo archivo en Windows → se inyectan CRLF. Solución:

git config --global core.autocrlf input    # dentro de WSL2

Más: /multi-os/git-line-endings.

6.4 EACCES en npm install -g

# Dentro de WSL2 — cambiar el prefijo de npm
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bashrc
exec bash

En Windows nativo, usa un PowerShell como administrador.

7. Verificación (en cualquiera de los entornos elegidos)

# WSL2 o PowerShell
node --version
npm --version
 
# Crear package.json + instalar dep + ejecutar
mkdir hello-node && cd hello-node
npm init -y
npm install express
cat > index.js <<'EOF'
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('hello'));
app.listen(3000, () => console.log('http://localhost:3000'));
EOF
node index.js
# → navegador localhost:3000 → «hello»

Si eso funciona, la configuración está lista.

8. Resolución de problemas

Cannot find module 'sharp' (u otro módulo nativo)

• Windows nativo: instala Visual Studio Build Tools, luego npm rebuild
• WSL2: sudo apt install build-essential, luego npm rebuild

El servidor de desarrollo no es accesible desde el navegador de Windows (WSL2)

• Haz que la app escuche en 0.0.0.0 o :: (p. ej., next dev -H 0.0.0.0)
• Windows 11 22H2+ reenvía automáticamente; versiones anteriores acceden mediante localhost

Comando pnpm no encontrado (problema de PATH)

• Encuentra dónde pone npm install -g los binarios y añádelo al PATH
• Nativo: npm config get prefix → <prefix>\bin
• WSL2: $HOME/.npm-global/bin o la ruta de mise

node-gyp build «Python not found»

• Windows nativo: winget install Python.Python.3.12
• WSL2: sudo apt install python3 python3-pip

¿Puedo compilar Electron desde WSL2?

Es posible, pero complejo. El empaquetado de Electron produce artefactos del sistema operativo anfitrión (.exe / .app / .deb), por lo que las compilaciones para Windows pertenecen a Windows nativo y las de Linux a WSL2. Para Electron, prefiere Windows nativo.

El servidor de desarrollo de Next.js se reinicia constantemente (WSL2)

No trabajes en /mnt/c/ (§6.2). También usa turbopack o configura las opciones de webpackDevMiddleware en next.config.ts.

9. Qué sigue

• Docker en WSL2 — /windows/docker-wsl2
• Ajuste de WSL (memoria, CPU, red) — /windows/wsl-tuning
• Configuración inicial de Windows — /windows/initial-setup
• La misma configuración en Mac — /mac/dev-toolchain (mise funciona de forma idéntica)

Referencias

• Node.js oficial
• mise oficial
• fnm en GitHub
• Documentación de VS Code WSL

Registro de cambios

• 2026-05-16: Primer borrador. Comparación WSL vs Nativo + ambas rutas de configuración + cuatro problemas frecuentes + seis casos de resolución de problemas.