# 从官网下载 Node.js 安装包
# https://nodejs.org/
# 安装完成后 npm 自动可用
 
# 验证安装
node --version   # v24.x.x
npm --version    # v11.18.0

# 安装 nvm（Node Version Manager）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
 
# 安装 Node.js（自带 npm）
nvm install 24
nvm use 24
 
# 验证
npm --version

# Node.js 25+ 中单独安装 npm
npm install -g npm@latest

# 更新到最新版本
npm install -g npm@latest
 
# 更新到指定版本
npm install -g [email protected]
 
# Windows 用户使用 PowerShell（管理员权限）
npm install -g npm@latest

# 查看全局配置路径
npm config get userconfig
 
# 设置全局 registry（使用镜像源加速）
npm config set registry https://registry.npmmirror.com
 
# 设置代理
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
 
# 查看完整配置
npm config list

# .npmrc
registry=https://registry.npmmirror.com
 
# 作用域包使用私有 registry
@mycompany:registry=https://npm.mycompany.com/
 
# 设置日志级别
loglevel=warn
 
# 设置 save-exact，锁定精确版本
save-exact=true

# 设置认证 token（私有 registry 常用）
npm config set //npm.mycompany.com/:_authToken=<TOKEN>
 
# 或使用 legacy auth
npm config set //npm.mycompany.com/:_auth=<BASE64_AUTH>

mkdir my-project
cd my-project
npm init
# 或直接跳过交互式问答
npm init -y

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

# 安装生产依赖
npm install express
 
# 安装开发依赖
npm install --save-dev vitest
 
# 安装全局包
npm install -g typescript
 
# 安装指定版本
npm install [email protected]
 
# 安装作用域包
npm install @types/node

{
  "scripts": {
    "dev": "node --watch src/index.js",
    "build": "tsc",
    "test": "vitest run",
    "lint": "eslint src/",
    "start": "node dist/index.js"
  }
}

npm run dev
npm run build
npm test

# 登录 npm 账号
npm login
 
# 发布公开包
npm publish
 
# 发布作用域包（需设置 access）
npm publish --access public
 
# 发布预发布版本
npm publish --tag beta

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "express": "^4.21.0"
  },
  "devDependencies": {
    "vitest": "^2.0.0"
  },
  "peerDependencies": {
    "react": ">=18.0.0"
  },
  "optionalDependencies": {
    "fsevents": "^2.3.3"
  },
  "overrides": {
    "minimist": "^1.2.8"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "scripts": {
    "build": "tsc",
    "test": "vitest"
  }
}

{
  "name": "my-app",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "my-app",
      "version": "1.0.0",
      "dependencies": {
        "express": "^4.21.0"
      }
    },
    "node_modules/express": {
      "version": "4.21.2",
      "resolved": "https://registry.npmjs.org/express/-/express-4.21.2.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "accepts": "~1.3.8"
      }
    }
  }
}

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

# 在工作区安装包
npm install lodash --workspace=packages/utils
 
# 在工作区运行脚本
npm run build --workspace=apps/web
 
# 链接工作区包（自动）
# 工作区之间互相引用自动使用 symlink

npm install lodash          # ^4.17.21（默认，兼容更新）
npm install lodash@~4.17.0  # ~4.17.x（仅补丁更新）
npm install [email protected]  # 精确版本
npm install lodash@>=4.0.0  # 范围匹配
npm install lodash@*        # 最新版本
npm install lodash@latest   # latest 标签
npm install lodash@next     # next 标签

{
  "scripts": {
    "preinstall": "node scripts/check-node-version.js",
    "postinstall": "node scripts/build-native.js",
    "prebuild": "npm run lint",
    "build": "tsc",
    "postbuild": "node scripts/copy-assets.js",
    "prepare": "husky install"
  }
}

# 执行本地 node_modules 中的命令
npx vitest run
 
# 临时下载并执行包
npx create-next-app@latest my-app
 
# 指定版本执行
npx @angular/cli@17 new my-project
 
# 执行 GitHub gist
npx https://gist.github.com/user/gist-id

# 审计当前项目依赖
npm audit
 
# 以 JSON 格式输出
npm audit --json
 
# 自动修复可修复的漏洞
npm audit fix
 
# 强制修复（可能引入破坏性变更）
npm audit fix --force

# 自动升版并发布
npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0
 
# 发布预发布版本
npm version prerelease --preid=beta
# 1.0.0 → 1.0.1-beta.0
 
# 发布到指定 tag
npm publish --tag next
 
# 撤销发布（72 小时内）
npm unpublish [email protected]
 
# 废弃版本（不删除，标记为废弃）
npm deprecate my-package@"<1.0.0" "该版本已废弃，请升级到 1.0.0+"

{
  "overrides": {
    "minimist": "^1.2.8",
    "semver": {
      ".": "^7.5.4",
      "nested-dep": "2.0.0"
    }
  }
}

# 查看缓存目录
npm config get cache
 
# 清理缓存
npm cache clean --force
 
# 验证缓存完整性
npm cache verify

# 创建作用域包
mkdir @mycompany/utils
npm init --scope=@mycompany
 
# 安装作用域包
npm install @mycompany/utils
 
# 发布作用域包
npm publish --access public

# 查看当前项目依赖中哪些接受赞助
npm fund
 
# 查看依赖的问题追踪器
npm bugs express
# 打开 https://github.com/expressjs/express/issues

# 典型的 Node.js 项目工作流
npm install          # 安装依赖
npm run dev          # 开发模式启动
npm run build        # 构建生产版本
npm test             # 运行测试
npm start            # 生产模式启动

# monorepo 典型结构
my-monorepo/
├── package.json          # 定义 workspaces
├── packages/
│   ├── ui/              # 共享 UI 组件库
│   ├── utils/           # 工具函数库
│   └── config/          # 共享配置
└── apps/
    ├── web/             # Web 应用
    └── mobile/          # 移动端应用

{
  "name": "my-cli",
  "bin": {
    "my-cli": "./dist/cli.js"
  }
}

# GitHub Actions 示例
- uses: actions/setup-node@v4
  with:
    node-version: '24'
    cache: 'npm'
- run: npm ci
- run: npm test
- run: npm run build

# 1. 项目初始化
npm init -y
 
# 2. 安装开发依赖
npm install -D typescript vitest eslint @types/node
 
# 3. 配置 scripts
# package.json 中定义开发脚本
{
  "scripts": {
    "dev": "tsc --watch",
    "build": "tsc",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix",
    "typecheck": "tsc --noEmit",
    "prepare": "husky install"
  }
}
 
# 4. 开发循环
npm run dev       # 终端 1：TypeScript 监听编译
npm run test:watch # 终端 2：测试监听

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20, 22, 24]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm run typecheck
      - run: npm test
      - run: npm run build

# 在根目录执行
npm install                  # 安装所有工作区依赖
npm install lodash -w packages/utils   # 为特定工作区安装依赖
 
# 运行工作区脚本
npm run build --workspace=packages/ui
npm run build --workspace=apps/web
 
# 列出所有工作区
npm query ':workspace'
 
# 过滤工作区执行
npm run test --workspace=packages/*

// packages/ui/package.json
{
  "name": "@mycompany/ui",
  "version": "1.0.0",
  "dependencies": {
    "@mycompany/utils": "workspace:*"  // npm workspaces 协议
  }
}

{
  "scripts": {
    // 并行运行多个开发服务器
    "dev": "concurrently \"npm:dev:*\"",
    "dev:server": "node --watch src/server.js",
    "dev:client": "vite",
 
    // 构建流水线（串行，使用 &&）
    "build": "npm run clean && npm run typecheck && npm run compile && npm run bundle",
    "clean": "rimraf dist",
    "typecheck": "tsc --noEmit",
    "compile": "tsc",
    "bundle": "rollup -c",
 
    // 测试流水线
    "test": "npm run test:unit && npm run test:e2e",
    "test:unit": "vitest run --coverage",
    "test:e2e": "playwright test",
 
    // 发布流水线
    "release": "npm run build && npm test && npm publish"
  }
}

# 1. 使用 npm ci 替代 npm install（CI 环境）
npm ci --prefer-offline
 
# 2. 优先使用本地缓存
npm install --prefer-offline
 
# 3. 减少网络请求
npm install --maxsockets 50   # 增加并发数
 
# 4. 跳过可选依赖（Docker/CI 优化）
npm install --omit=optional
 
# 5. 使用 --ignore-scripts 跳过安装脚本
npm install --ignore-scripts  # 安全敏感场景

# 显式允许安装脚本
npm install --ignore-scripts=false
 
# 或在全局配置中允许
npm config set ignore-scripts false
 
# 在项目 .npmrc 中配置
ignore-scripts=false

# 不再允许：
npm install github:user/repo
npm install git+https://github.com/user/repo.git
 
# 显式允许：
npm install --allow-git=github.com/user/repo

# 不再允许：
npm install https://example.com/package.tgz
 
# 显式允许：
npm install --allow-remote=true

# 基础审计
npm audit
 
# 按严重级别过滤
npm audit --audit-level=high
 
# 查看详细信息
npm audit --verbose
 
# JSON 输出（集成到安全工具链）
npm audit --json | jq '.vulnerabilities'
 
# 自动修复
npm audit fix
 
# 生产环境审计（跳过 devDependencies）
npm audit --omit=dev

# 1. 定期审计
npm audit
 
# 2. 锁定精确版本（减少不确定性）
npm config set save-exact true
 
# 3. 验证包完整性
# npm 自动验证 tarball integrity hash
 
# 4. 使用 --ignore-scripts 减少攻击面
npm install --ignore-scripts
 
# 5. 限制 registry 来源
# .npmrc
registry=https://registry.npmjs.org/
# 禁止从其他来源下载

# .npmrc
save-exact=true

// package.json 中使用精确版本
{
  "dependencies": {
    "express": "4.21.2",     // 不使用 ^ 或 ~
    "lodash": "4.17.21"
  }
}

# 始终使用 npm ci 而非 npm install
- run: npm ci --prefer-offline --no-audit

FROM node:24-slim
 
WORKDIR /app
 
# 仅复制 lock 文件，利用 Docker 缓存
COPY package.json package-lock.json ./
 
# 仅安装生产依赖
RUN npm ci --omit=dev --ignore-scripts --prefer-offline
 
# 复制源码
COPY . .
 
CMD ["node", "dist/index.js"]

// package.json
{
  "scripts": {
    "audit": "npm audit --audit-level=high",
    "audit:fix": "npm audit fix",
    "audit:json": "npm audit --json > audit-report.json"
  }
}

# .npmrc（生产项目推荐配置）
registry=https://registry.npmjs.org/
save-exact=true
loglevel=warn
audit-level=high
 
# 禁用安装脚本（安全）
ignore-scripts=true
 
# 引擎检查
engine-strict=true
 
# 禁止从 Git 安装（npm v12 默认）
allow-git=

// package.json
{
  "engines": {
    "node": ">=22.0.0",
    "npm": ">=11.0.0"
  },
  "scripts": {
    "preinstall": "node scripts/check-engines.js",
    "prepare": "husky install"
  }
}

# 检查过时依赖
npm outdated
 
# 使用 npm-check-updates 批量更新
npx npm-check-updates -u
npm install
 
# 使用 Renovate / Dependabot 自动化更新
# 在 CI 中自动创建更新 PR

# 提前测试 v12 兼容性
nvm install 25  # Node.js 25 可能默认包含 v12
 
# 检查项目是否依赖安装脚本
npm ls --json | grep -E "preinstall|install|postinstall"
 
# 为已知安全的包允许安装脚本
# .npmrc
allow-scripts=true
# 或使用白名单
# allow-scripts=@esbuild/postinstall,@prisma/client