npm_guide

npm 使用指南

npm (Node Package Manager) 是 Node.js 的默认包管理器，也是世界上最大的软件注册表。开发者使用 npm 来发现、共享和使用代码包。本指南将全面介绍 npm 的常用功能和命令。

1. npm 是什么？

  • 包管理器: npm 帮助开发者管理项目所依赖的外部代码库（称为“包”或“模块”）。
  • 命令行工具: npm 提供了一个命令行客户端，用于与 npm 注册表交互，执行安装、更新、发布等操作。
  • 在线注册表: npm 维护着一个庞大的公共代码库（npm registry），开发者可以在这里查找和下载包，也可以将自己的包发布上去供他人使用。

2. 安装 Node.js 和 npm

npm 通常随 Node.js 一起安装。你可以从 Node.js 官方网站 下载并安装适合你操作系统的 Node.js 版本。安装完成后，可以在终端或命令提示符中运行以下命令来验证 Node.js 和 npm 是否安装成功：

node -v
npm -v

3. package.json 文件

package.json 文件是每个 Node.js 项目的核心配置文件。它包含了项目的元数据（如名称、版本、描述）和依赖信息。

作用：

  • 描述项目信息。
  • 管理项目依赖。
  • 定义可执行脚本。
  • 使得项目构建可重复。

主要字段：

  • name: 项目名称（必须小写，可以包含连字符和下划线）。
  • version: 项目版本号（遵循 SemVer 规范）。
  • description: 项目描述。
  • main: 项目的入口文件（通常是 index.js）。
  • scripts: 定义可运行的脚本命令（例如 start, test, build）。
  • dependencies: 项目在生产环境中需要的依赖包。
  • devDependencies: 项目在开发环境中需要的依赖包（例如测试框架、构建工具）。
  • author: 项目作者。
  • license: 项目许可证（例如 MIT, ISC）。
  • repository: 项目代码仓库信息。
  • keywords: 关键词，便于在 npm 搜索。

4. 初始化项目 (npm init)

在一个新的项目目录下，运行 npm init 命令可以创建一个 package.json 文件。它会引导你填写项目的基本信息。

npm init

如果你想快速生成一个默认配置的 package.json 文件，可以使用 -y 或 --yes 标志：

npm init -y

5. 安装依赖包 (npm install)

npm install (或简写 npm i) 命令用于安装项目依赖。

本地安装 vs 全局安装

  • 本地安装 (默认): 将包安装到当前项目的 node_modules 目录下，并记录到 package.json 文件中。这是最常用的方式。

    # 安装一个生产依赖
npm install <package_name>
npm install <package_name> --save # 旧版 npm 需要 --save，新版默认

# 安装一个开发依赖
npm install <package_name> --save-dev
npm i <package_name> -D # 简写

  • 全局安装: 将包安装到系统的全局目录中，通常用于安装命令行工具。

    npm install <package_name> -g
npm i <package_name> --global

--save vs --save-dev

  • --save (或 -S，在新版 npm 中是默认行为): 将包添加到 dependencies。
  • --save-dev (或 -D): 将包添加到 devDependencies。

从 package.json 安装

如果项目已有 package.json 文件（例如从 Git 克隆下来的项目），可以直接运行 npm install 来安装所有在 dependencies 和 devDependencies 中定义的依赖：

npm install
npm i

6. 更新依赖包 (npm update)

npm update 命令用于将项目依赖更新到 package.json 文件中允许的最新版本。

# 更新所有依赖
npm update

# 更新指定的包
npm update <package_name>

要更新到最新的主版本（可能会有破坏性更新），通常需要先检查更新，然后手动修改 package.json 并重新运行 npm install，或者使用 npm install <package_name>@latest。

7. 卸载依赖包 (npm uninstall)

npm uninstall (或 npm rm, npm un) 命令用于从项目中移除依赖包。

# 卸载一个包（同时会从 dependencies 或 devDependencies 中移除）
npm uninstall <package_name>

# 卸载一个全局安装的包
npm uninstall <package_name> -g

8. 查看已安装的包 (npm list)

npm list (或 npm ls) 命令用于查看当前项目已安装的包及其依赖关系。

# 查看顶层依赖
npm list --depth=0
npm ls -depth=0

# 查看全局安装的顶层依赖
npm list -g --depth=0

9. 运行脚本 (npm run)

npm run 命令用于执行在 package.json 文件 scripts 字段中定义的脚本。

// package.json
"scripts": {
  "start": "node index.js",
  "test": "jest",
  "build": "webpack --config webpack.config.js"
}
# 运行 start 脚本
npm run start
npm start # 对于 start, test, stop, restart 可以省略 run

# 运行 test 脚本
npm run test
npm test

# 运行 build 脚本
npm run build

# 查看所有可运行的脚本
npm run

10. 发布包到 npm registry (npm publish)

如果你开发了一个可重用的 Node.js 模块，可以将其发布到 npm registry 供他人使用。

  1. 登录 npm 账户: 
    npm login
    （需要先在 npmjs.com 注册账户）
  2. 确保 package.json 信息完整: 特别是 name, version, main 等字段。包名必须是唯一的。
  3. 发布包: 
    npm publish
    （每次发布前通常需要更新 version 字段）

11. npm 常用命令总结

命令简写描述
npm init初始化项目，创建 package.json
npm init -y使用默认配置快速初始化项目
npm installnpm i安装 package.json 中的所有依赖
npm install <pkg>npm i <pkg>安装指定的包（本地，生产依赖）
npm install <pkg> -Dnpm i <pkg> -D安装指定的包（本地，开发依赖）
npm install <pkg> -gnpm i <pkg> -g全局安装指定的包
npm update更新所有依赖到允许的最新版本
npm update <pkg>更新指定的包
npm uninstall <pkg>npm rm <pkg>卸载指定的包（本地）
npm uninstall <pkg> -gnpm rm <pkg> -g卸载指定的包（全局）
npm listnpm ls列出已安装的包
npm list -g --depth=0npm ls -g -depth=0列出全局安装的顶层包
npm run <script>运行 package.json 中定义的脚本
npm start运行 start 脚本
npm test运行 test 脚本
npm stop运行 stop 脚本
npm restart运行 restart 脚本
npm search <keyword>在 npm registry 中搜索包
npm view <pkg>npm v <pkg>查看包的详细信息
npm outdated检查过期的依赖
npm publish发布包到 npm registry
npm login登录 npm 账户
npm logout登出 npm 账户
npm config list查看 npm 配置
npm config set <key> <value>设置 npm 配置项
npm config get <key>获取 npm 配置项的值
npm cache clean --force清理 npm 缓存（有时用于解决安装问题）
npx <command>执行 npm 包中的命令，无需全局安装

12. npm 配置 (npm config)

npm 的行为可以通过配置文件进行修改。常见的配置包括设置代理、修改 registry 地址等。

# 查看所有配置
npm config list

# 查看 registry 地址
npm config get registry

# 设置淘宝镜像 registry
npm config set registry https://registry.npmmirror.com

# 删除某个配置项
npm config delete registry

# 编辑配置文件
npm config edit

配置文件有多个级别：项目级 (.npmrc 文件)、用户级、全局级。

13. 使用 npx

npx 是 npm v5.2.0 引入的一个工具，用于执行 npm 包中的可执行文件。

主要用途：

  • 临时运行包命令: 无需全局或本地安装即可运行某个包提供的命令。 
    npx create-react-app my-app # 运行 create-react-app 包来创建 React 应用
  • 运行本地安装的命令: 可以直接运行 node_modules/.bin 目录下的命令，无需配置 npm run 脚本。 
    # 假设本地安装了 mocha
npx mocha # 等同于 ./node_modules/.bin/mocha
  • 测试不同版本的 Node.js 或 npm 包: 
    npx node@14 -v # 使用 Node.js 14 版本执行命令

14. npm 镜像和私有仓库（可选）

  • npm 镜像: 由于 npm 官方 registry 在某些地区访问速度较慢，可以使用国内的镜像源（如淘宝 NPM 镜像）来加速下载。

    # 临时使用淘宝镜像安装
npm install <package_name> --registry=https://registry.npmmirror.com

# 永久设置淘宝镜像
npm config set registry https://registry.npmmirror.com

    推荐使用 nrm 或 yrm 等工具来管理不同的 registry 源。

  • 私有仓库: 对于企业或团队内部使用的包，可以搭建私有 npm 仓库（如 Verdaccio, Nexus Repository Manager 等），用于存储和管理内部包，同时可以缓存公共包。

15. Node.js 基本使用

虽然 npm 是 Node.js 的包管理器，但了解 Node.js 本身的基本用法对于充分利用 npm 和 JavaScript 生态系统至关重要。

运行 JavaScript 脚本

最常见的 Node.js 用法是执行 .js 文件。假设你有一个名为 my_script.js 的文件：

// my_script.js
const message = "Hello from Node.js!";
console.log(message);

你可以在终端中使用 node 命令来运行它：

node my_script.js

终端将输出：Hello from Node.js!

Node.js REPL (交互式解释器)

Node.js 提供了一个 REPL (Read-Eval-Print Loop) 环境，这是一个交互式的命令行界面，你可以在其中输入 JavaScript 代码并立即看到结果。

在终端中直接运行 node 命令即可进入 REPL：

node

你会看到一个 > 提示符。现在你可以输入 JavaScript 代码：

> const x = 5;
undefined
> x + 10
15
> console.log('Node.js is fun!');
Node.js is fun!
undefined
> .exit // 或按两次 Ctrl+C 退出 REPL

REPL 对于快速测试代码片段、学习 JavaScript 语法或探索 Node.js 功能非常有用。

核心模块 (Core Modules)

Node.js 内置了许多核心模块，提供了文件系统操作、网络通信、路径处理等基本功能，无需额外安装。你可以使用 require 函数来加载这些模块。

  • fs (File System): 用于与文件系统交互，如读写文件。

    const fs = require("fs");

// 读取文件内容 (异步)
fs.readFile("my_script.js", "utf8", (err, data) => {
  if (err) throw err;
  console.log(data);
});

// 写入文件 (同步)
try {
  fs.writeFileSync("new_file.txt", "This is some content.");
  console.log("File written successfully!");
} catch (err) {
  console.error("Error writing file:", err);
}

  • http: 用于创建 HTTP 服务器和客户端。

    const http = require("http");

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Hello World\n");
});

server.listen(3000, "127.0.0.1", () => {
  console.log("Server running at http://127.0.0.1:3000/");
});

  • path: 提供处理文件和目录路径的工具。

    const path = require("path");

const filePath = "/users/test/file.txt";
console.log(path.dirname(filePath)); // 输出: /users/test
console.log(path.basename(filePath)); // 输出: file.txt
console.log(path.extname(filePath)); // 输出: .txt
console.log(path.join("/users", "test", "another_file.md")); // 输出: /users/test/another_file.md (跨平台兼容)

还有许多其他核心模块，如 os (操作系统信息), events (事件处理), url (URL 解析) 等。你可以查阅 Node.js 官方文档 获取完整列表和详细用法。

应用场景

Node.js 因其非阻塞 I/O 和事件驱动的特性，在许多领域都有广泛应用：

  • Web 服务器: 构建高性能的后端 API 和 Web 应用 (常与 Express, Koa 等框架结合)。
  • 命令行工具 (CLI): 开发各种实用的命令行工具。
  • 构建工具: 前端开发中常用的构建、打包、自动化工具（如 Webpack, Gulp, Grunt）通常基于 Node.js。
  • 实时应用: 如聊天室、在线游戏等需要实时通信的应用。
  • 微服务: 构建独立的、可扩展的服务单元。

掌握 Node.js 的基本用法将为你使用 npm 管理项目依赖、运行脚本以及进行更广泛的 JavaScript 开发打下坚实的基础。

希望这份指南能帮助你更好地理解和使用 npm！