Node.js: Gerenciador npm

Última atualização: 2026-08-26

Alice acabara de assumir um novo projeto que exigia a inclusão da biblioteca Luxon para gerenciamento de datas e da estrutura HTTP Express, além da configuração da ferramenta de testes Jest. No início, ela baixava os arquivos JavaScript um por um dos sites oficiais e os copiava manualmente para o projeto, mas sempre se deparava com conflitos de versão, e atualizar tudo era um pesadelo. Isso até que um colega lhe apresentou o npm — um único comando para instalar dependências, com as versões registradas no パッケージ.json e fixadas nas versões exatas por meio do arquivo ロック. Desde então, a equipe nunca mais enfrentou o problema do tipo “funciona na minha máquina”.

Você aprenderá:

• Use npm init, npm install e npm uninstall para gerenciar as dependências do projeto
• Distinguir entre dependências e devDependencies e seus respectivos casos de uso
• Compreender o objetivo do パッケージ-ロック.json e a estratégia de コミット
• Compreender as regras de versionamento semântico do SemVer (^, ~, >=, etc.)
• Aumente a eficiência do desenvolvimento com os scripts do npm e o npx

1. npm init — Inicializar um projeto

(1) Inicialização interativa

Ao executar o npm init, você será solicitado a inserir as informações do projeto passo a passo, gerando, por fim, o パッケージ.json.

▶ Exemplo: Como criar um arquivo package.json de forma interativa

mkdir my-project && cd my-project
npm init

package name: (my-project)
version: (1.0.0)
description: A sample project. Este guia para iniciantes cobre this topic com explicações claras e exemplos práticos. Comece a aprender hoje!
entry point: (index.js)
test command: jest
git repository:
keywords:
author: Alice
license: (ISC)

(2) Inicialização rápida

Use -y para pular todas as solicitações e gerar o padrão package.json.

▶ Exemplo: Ignore as instruções para gerar rapidamente

npm init -y

Wrote to /home/alice/my-project/package.json

Conteúdo padrão gerado パッケージ.json:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "license": "ISC"
}

2. npm install / uninstall — Instalando e desinstalando dependências

(1) Instalar dependências

npm install <package> Baixe o pacote para node_modules e grave-o em package.json.

▶ Exemplo: Instalação de dependências de produção

npm install express

(2) Instalar dependências de desenvolvimento

--save-dev (abreviado como -D) registra pacotes no devDependencies e destina-se exclusivamente ao uso em ambientes de desenvolvimento.

▶ Exemplo: Instalação de dependências de desenvolvimento

npm install jest --save-dev

(3) Desinstalar dependências

npm uninstall Exclua os dois arquivos em node_modules e os registros em package.json.

▶ Exemplo: Desinstalação de uma dependência

npm uninstall express

(4) Instalar todas as dependências

Depois de clonar o projeto de outra pessoa, execute npm install para restaurar todas as dependências usando package.json e package-lock.json.

▶ Exemplo: Restaurando dependências

npm install

3. dependências vs. devDependencies

(1) Classificação de dependências

dependencies Lista os pacotes necessários para o ambiente de produção; devDependencies lista os pacotes utilizados apenas durante a fase de desenvolvimento.

▶ Exemplo: Seções de dependências no arquivo package.json

{
  "dependencies": {
    "express": "^4.18.2",
    "luxon": "^3.4.4"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "eslint": "^8.56.0"
  }
}

(2) Ignorar dependências de desenvolvimento durante a instalação em produção

Use --production ou defina NODE_ENV=production para ignorar a instalação das devDependencies e reduzir o tamanho da implantação.

▶ Exemplo: Instalação em um ambiente de produção

npm install --production

4. A finalidade do arquivo package-lock.json

(1) Fixar a versão exata

パッケージ-ロック.json Registre a versão exata e o hash de integridade de cada dependência para garantir que os resultados da instalação sejam consistentes em todos os ambientes.

(2) Aumentar a velocidade de instalação

O arquivo ロック contém a árvore completa de dependências, permitindo que o npm pule a resolução de versões e baixe os pacotes diretamente.

▶ Exemplo: trecho do arquivo ロック

{
  "node_modules/luxon": {
    "version": "3.4.4",
    "resolved": "https://registry.npmjs.org/luxon/-/luxon-3.4.4.tgz",
    "integrity": "sha512-zaBViHBuQffgP8h...',
    "requires": {}
  }
}

5. Versionamento Semântico (SemVer)

(1) Formato do número da versão

O formato SemVer é MAJOR.MINOR.PATCH, sendo que cada componente tem um significado específico.

(2) Símbolos de intervalo de versões

Use os símbolos em package.json para restringir o intervalo de versões aceitáveis.

▶ Exemplo: Resultados reais para diferentes intervalos

{
  "express": "^4.18.2",
  "lodash": "~4.17.21",
  "axios": ">=1.6.0",
  "デバッグ": "4.3.x"
}

(3) Regras para atualização de versão

• PATCH: Corrige bugs sem alterar a API
• MINOR (versão secundária): Novos recursos, compatível com versões anteriores
• MAJOR (Versão principal): Alterações que quebram a compatibilidade; sem compatibilidade com versões anteriores

6. Instalação global x instalação local

(1) Instalação local

Por padrão, o pacote é instalado no projeto node_modules; projetos diferentes podem usar versões diferentes.

(2) Instalação global

Adicione o sinalizador -g para instalar o pacote no diretório global do sistema e fornecer uma ferramenta de linha de comando.

▶ Exemplo: Instalando uma ferramenta de linha de comando globalmente

npm install -g nodemon

(3) Quando utilizar uma instalação global

Instale apenas as ferramentas que exigem acesso à linha de comando (como o nodemon e o pm2); as dependências do projeto devem ser sempre instaladas localmente.

7. Scripts do npm

(1) Scripts integrados

start e test são scripts integrados do npm que podem ser executados diretamente usando npm start / npm test.

(2) Scripts personalizados

Outros scripts devem ser executados usando npm run <name>.

▶ Exemplo: Configurando scripts comuns

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest --coverage",
    "lint": "eslint src/"
  }
}

npm start
npm run dev
npm test
npm run lint

(3) Ganchos entre scripts

pre<script> e post<script> são executados automaticamente antes e depois do script de destino.

▶ Exemplo: Como usar o gancho pre

{
  "scripts": {
    "prebuild": "npm run lint",
    "build": "node build.js",
    "postbuild": "echo Build complete"
  }
}

Ao executar npm run build, prebuild → build → postbuild será executado em sequência.

8. O comando npx

(1) Executar temporariamente um pacote remoto

npx Permite executar pacotes não instalados diretamente, evitando a contaminação global.

▶ Exemplo: Uso temporário do create-react-app

npx create-react-app my-app

(2) Executar um comando em um sistema instalado localmente

O npx verificará primeiro se node_modules/.bin está disponível localmente, depois globalmente e, por fim, fará o download remotamente.

▶ Exemplo: Executando uma ferramenta local

npx jest

(3) Executar uma versão específica

▶ Exemplo: Como usar uma versão específica de um pacote

npx express-generator@4 --view=ejs my-site

9. Configuração do .npmrc

(1) Hierarquia dos arquivos de configuração

.npmrc Oferece suporte a três níveis: nível de projeto, nível de usuário e nível global, em ordem decrescente de prioridade.

▶ Exemplo: Configurando fontes de espelho em um arquivo .npmrc no nível do projeto

registry=https://registry.npmmirror.com

(2) Opções comuns de configuração

▶ Exemplo: Definindo a configuração por meio de um comando

npm config set registry https://registry.npmmirror.com
npm config get registry
npm config list

10. O processo de execução do “npm install”

flowchart TD
    A[npm install] --> B{Does it exist? package-lock.json?}
    B -- Yes --> C[Read lock The exact version in the document]
    B -- No --> D[Analysis package.json Version range in]
    D --> E[Search registry Get the latest compatible version]
    E --> F[Generate a dependency tree]
    C --> G[Download the package to the cache]
    F --> G
    G --> H[Write node_modules Table of Contents]
    H --> I[Update package-lock.json]
    I --> J[Installation Complete]

flowchart TD
    A[npm install] --> B{Does it exist? package-lock.json?}
    B -- Yes --> C[Read lock The exact version in the document]
    B -- No --> D[Analysis package.json Version range in]
    D --> E[Search registry Get the latest compatible version]
    E --> F[Generate a dependency tree]
    C --> G[Download the package to the cache]
    F --> G
    G --> H[Write node_modules Table of Contents]
    H --> I[Update package-lock.json]
    I --> J[Installation Complete]

11. Exemplo completo: como configurar as dependências do projeto do zero

O exemplo a seguir demonstra todo o processo de como Alice cria um projeto do zero, instala dependências, configura scripts e inicia o servidor de desenvolvimento.

mkdir alice-server && cd alice-server
npm init -y

npm install express luxon
npm install jest nodemon --save-dev

パッケージ.json após a instalação:

{
  "name": "alice-server",
  "version": "1.0.0",
  "description": "Alice's date-aware HTTP server",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.2",
    "luxon": "^3.4.4"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "nodemon": "^3.0.2"
  },
  "license": "ISC"
}

Crie o arquivo de entrada index.js:

const express = require('express');
const { DateTime } = require('luxon');

const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
  const now = DateTime.now().toISO();
  res.json({ message: 'Server is running', timestamp: now });
});

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

Inicie o servidor de desenvolvimento:

npm run dev

[nodemon] starting node index.js
Server listening on port 3000

❓ Perguntas Frequentes

P: O package-lock.json deve ser enviado ao Git? R: Sim. Isso fixa as versões exatas e os hashes de integridade, garantindo que os resultados da instalação sejam consistentes em toda a equipe e no ambiente de CI.

P: O node_modules deve ser enviado ao Git? R: Não. Ele é muito grande e pode ser restaurado usando o npm install, portanto, deve ser adicionado ao .gitignore.

P: Qual é a diferença entre ^1.2.3 e ~1.2.3? R: O símbolo ^ permite atualizações de versão secundária (>=1.2.3 <2.0.0), enquanto o símbolo ~ permite apenas atualizações de patch (>=1.2.3 <1.3.0).

P: Qual é a diferença entre npx e npm exec? R: npm exec é o comando equivalente fornecido pelo npm v7 e versões posteriores; eles funcionam da mesma forma, mas npx é mais curto e compatível com versões anteriores.

P: Como faço para verificar a versão de um pacote instalado? R: Use npm list para visualizar sua árvore de dependências local e npm outdated para verificar quais pacotes têm atualizações.

P: O que devo fazer se o npm install apresentar um erro de permissão EACCES? R: Evite usar o sudo. Recomendamos definir o diretório global para um caminho no qual o usuário tenha permissão de gravação usando o npm config set prefix.

P: Os pacotes listados em “dependencies” são instalados em um ambiente de produção? R: Sim. O npm install instala as “dependencies” por padrão; é necessário usar o sinalizador --production para ignorar as “devDependencies”.

📖 Resumo

• Use npm init para inicializar o projeto; use -y para pular as solicitações
• instalar/desinstalar e gerenciar dependências; a opção -D adiciona as dependências à lista devDependencies
• O arquivo package-lock.json define as versões específicas; deve ser enviado ao controle de versão
• O SemVer usa ^/~/>= para controlar os intervalos de versão
• As instalações globais se aplicam apenas às ferramentas de linha de comando; todas as dependências do projeto devem ser instaladas localmente.
• Os scripts do npm simplificam comandos comuns; “start” e “test” podem ser omitidos e substituídos por “run”
• npx: Executa pacotes remotos temporariamente, sem a necessidade de uma instalação global
• O .npmrc oferece três níveis de configuração: projeto, usuário e global

📝 Exercícios

1. Execute npm init -y para criar um projeto e, em seguida, edite manualmente o nome, a descrição e os scripts no arquivo package.json
2. Instale express e luxon como dependências e instale jest como uma devDependency; em seguida, observe as alterações no arquivo package.json
3. Use npm list e npm outdated para verificar o status da dependência, respectivamente
4. Crie o arquivo .npmrc, defina o registro como https://registry.npmmirror.com e reinstale para verificar.
5. Escreva um script personalizado hello que exiba “Olá, dos scripts do npm” e execute-o usando npm run hello

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós