Appearance
Node.js & npm 开发与发布实用笔记
一、 npm 基础与常用命令
1. 基础环境查看
bash
node -v # 查看 Node.js 版本
npm -v # 查看 npm 版本2. 初始化项目
bash
npm init -y # 快速跳过配置，直接生成默认的 package.json3. 依赖包版本查看与安装
bash
# 查看远程包的版本信息
npm view <package-name> version # 查看最新版本
npm view <package-name> versions # 查看所有发布过的版本
# 安装指定版本
npm install <package-name>@latest # 安装最新版本
npm install <package-name>@<版本号> # 安装指定版本（例如 express@5.2.1）
# 查看全局安装的包
npm list -g --depth=0 # 查看全局包列表（--depth=0 可避免展开层级）二、 环境配置与国内镜像源
使用 npm config edit 可以直接打开配置文件进行编辑。以下是常用的国内淘宝/腾讯等镜像源及二进制文件加速配置：
ini
# 设置 npm 镜像源（双胞胎镜像：腾讯云/淘宝）
registry=https://registry.npmmirror.com
# 常用二进制依赖加速
electron_mirror=https://cdn.npmmirror.com/binaries/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/💡 避坑提示：如果平时使用了
npmmirror镜像，在执行npm publish发布包之前，必须先切回官方源：npm config set registry [https://registry.npmjs.org](https://registry.npmjs.org)
三、 Node 多版本管理工具 n
n 是一个非常轻量化的 Node.js 版本管理器（注：仅支持 Linux 和 macOS，Windows 用户建议使用 nvm-windows）。
bash
npm install -g n # 全局安装 n
n stable # 升级/切换到最新的稳定版 (Stable)
n latest # 升级/切换到最新的开发版 (Latest)
n lsr # 查看官方所有可用的版本
n # 展示本地已安装的版本，通过上下键切切换
n v18.16.0 # 下载并切换到指定版本
n rm 18.16.0 # 删除指定的本地版本
n latest npm # 将当前环境的 npm 更新到最新版
# 免切换临时运行
n use 18.16.0 index.js # 使用指定版本执行特定脚本四、 常用开发依赖与应用打包 (pkg)
1. 常用核心依赖参考
express@5.2.1：轻量级 Web 开发框架。http-proxy@1.18.1：网关与反向代理服务组件。mysql2@3.20.0：高性能 MySQL 数据库驱动。nodemon@3.1.14：开发环境代码修改自动重启工具。
2. 使用 pkg 将 Node 项目打包为独立可执行文件
pkg 可以将 Node.js 项目打包成无需安装环境即可运行的 .exe 或二进制文件（支持跨平台编译）。
bash
# 全局安装
npm install -g pkg
# 命令格式
pkg <入口文件> --targets <平台架构> --output <输出文件路径>
# 示例：将项目打包为 Windows 64位可执行文件
pkg src/index.js --targets node18-win-x64 --output dist/app.exe五、 自定义 npm 包的目录结构与配置
一个规范 of npm 开源/私有包通常包含以下标准结构：
1. 标准目录结构
text
my-awesome-package/
├── src/ # 源代码目录
│ ├── index.js # 主入口文件
│ └── utils.js # 工具函数
├── lib/ # 编译后的代码（通常由 Babel/TS 生成，可选）
├── test/ # 单元测试目录
├── examples/ # 供用户参考的使用示例
├── README.md # 包的使用说明文档（非常重要）
├── package.json # 包的元数据与配置文件
├── .npmignore # 限制发布的文件黑名单（不写默认读取 .gitignore）
├── .gitignore # Git 忽略文件
├── LICENSE # 开源许可证（如 MIT）
└── CHANGELOG.md # 版本更新日志2. 核心 package.json 模板解析
json
{
"name": "my-awesome-package",
"version": "1.0.0",
"description": "一个超棒的 Node.js 包",
"main": "src/index.js",
"exports": {
".": "./src/index.js",
"./utils": "./src/utils.js"
},
"types": "./types/index.d.ts",
"scripts": {
"test": "jest",
"lint": "eslint src/",
"build": "babel src --out-dir lib",
"prepublishOnly": "npm test && npm run build"
},
"keywords": ["awesome", "utility", "nodejs"],
"author": "你的名字 <your-email@example.com>",
"license": "MIT",
"homepage": "https://github.com/yourname/my-awesome-package",
"repository": {
"type": "git",
"url": "git+https://github.com/yourname/my-awesome-package.git"
},
"bugs": {
"url": "https://github.com/yourname/my-awesome-package/issues"
},
"engines": {
"node": ">=14.0.0"
},
"dependencies": {
"lodash": "^4.17.21"
},
"devDependencies": {
"jest": "^29.0.0",
"eslint": "^8.0.0",
"@babel/cli": "^7.0.0",
"@babel/preset-env": "^7.0.0"
},
"files": [
"src",
"lib",
"types"
]
}💡
"prepublishOnly"钩子会在你执行npm publish时自动先触发，确保测试通过并构建成功后再上传，防止坏代码传到线上。"files"字段是一个白名单，用来指定哪些文件/文件夹会被包含在最终发布的安装包内。
六、 npm 账号管理与发布/更新流程
1. 首次发布包的完整步骤
bash
# 步骤 1: 检查包名是否在全球范围内被占用
npm view <package-name>
# 💡 如果返回 404，该名字尚未被使用，可以放心打包发布。
# 步骤 2: 登录 npm 官方账户（需切回官方源）
npm login
# 根据提示输入：Username, Password, Email 以及邮箱里的双因素验证码(OTP)
# 步骤 3: 检查当前登录状态是否成功
npm whoami
# 步骤 4: 在项目根目录下执行发布
npm publish
# 💡 如果是作用域包（Scoped，如 @myorg/package），需用：npm publish --access public
# 步骤 5: 验证线上是否存在
npm view <package-name>2. 更新已发布的包
bash
# 1. 升级版本号（三者选其一）
npm version patch # 1.0.0 → 1.0.1（修复 Bug）
npm version minor # 1.0.0 → 1.1.0（新增功能，向下兼容）
npm version major # 1.0.0 → 2.0.0（重大更新，不兼容旧版本）
# 2. 推送至远程 npm 服务器
npm publish
# 3. 可选：将 npm 自动生成的版本 Tag 推送到 Git 仓库
git push --tags3. 账户登出
bash
npm logout # 清除当前机器上的登录凭证