发布流程：npm publish + 语义化版本 + Git Tag

一个专业、可靠的工具库，不仅要有优秀的代码和文档，还必须具备可重复、可追溯、自动化的发布流程。

通过结合 npm publish、语义化版本（SemVer） 和 Git Tag，我们可以构建一个标准化的发布体系，确保每次发布都清晰、安全、可回溯。

核心组件概览

组件	作用
npm publish	将包发布到 npm registry，供全球开发者安装
语义化版本 (SemVer)	定义版本号规则，明确变更影响范围
Git Tag	在代码仓库中标记发布点，实现版本与源码的精确对应

最终目标：
执行一条命令或 CI 流程后，自动完成：

1. 版本号更新
2. 打 Git Tag
3. 构建产物
4. 发布到 npm
5. 推送标签

1. 语义化版本（Semantic Versioning）

遵循 semver.org 规范，版本格式为：MAJOR.MINOR.PATCH

版本部分	触发条件	示例
MAJOR	不兼容的 API 修改	1.0.0 → 2.0.0
MINOR	向后兼容的功能新增	1.0.0 → 1.1.0
PATCH	向后兼容的 bug 修复	1.0.0 → 1.0.1

示例场景

# 修复 deepGet 的空值处理 bug
npm version patch  # → 1.2.3 → 1.2.4

# 新增 pipeAsync 函数
npm version minor  # → 1.2.4 → 1.3.0

# 重构 omit 接口，移除旧参数
npm version major  # → 1.3.0 → 2.0.0

2. 手动发布流程（适用于小团队）

步骤 1：确保代码就绪

# 拉取最新代码
git pull origin main

# 确保测试通过
npm test

# 确保构建成功
npm run build

步骤 2：更新版本号并生成 Git Tag

# 使用 npm version 自动更新 package.json 并打 tag
npm version patch -m "release: %s"
# 输出：v1.0.1

-m "release: %s" 定制提交信息，%s 被替换为版本号。

步骤 3：推送代码和标签

git push origin main
git push origin v1.0.1

步骤 4：发布到 npm

npm publish
# 或发布预发布版本
# npm publish --tag next

步骤 5：验证

• 访问 https://www.npmjs.com/package/your-package
• 运行 npm view your-package version 确认版本

3. 自动化发布流程（推荐用于生产项目）

使用 GitHub Actions 实现 CI/CD 驱动的发布。

.github/workflows/release.yml

name: Release

on:
  push:
    tags:
      - 'v*'  # 监听以 v 开头的 tag

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 获取所有历史，便于生成 changelog

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci

      - name: Build
        run: npm run build

      - name: Test
        run: npm test

      - name: Generate Changelog (optional)
        run: npx standard-version --dry-run > CHANGELOG.md

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

4. 增强发布流程（专业级）

(1) 自动生成 Changelog

使用 standard-version：

npm install --save-dev standard-version

配置 package.json：

{
  "scripts": {
    "release": "standard-version"
  },
  "standard-version": {
    "types": [
      { "type": "feat", "section": "Features" },
      { "type": "fix", "section": "Bug Fixes" },
      { "type": "perf", "section": "Performance Improvements" },
      { "type": "docs", "hidden": true }
    ]
  }
}

提交时使用 Conventional Commits：

git commit -m "feat(pipe): add async support"
git commit -m "fix(omit): handle null input"

发布：

npm run release  # 自动生成 CHANGELOG.md，更新版本，打 tag
git push --follow-tags origin main
npm publish

(2) 预发布版本（Alpha/Beta/RC）

# 发布测试版
npm version 1.1.0-beta.1
git push origin main --tags
npm publish --tag beta

# 用户安装
# npm install your-package@beta

(3) 多平台构建支持

确保 package.json 正确声明入口：

{
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js"
    },
    "./object/omit": {
      "import": "./dist/esm/object/omit.js",
      "require": "./dist/cjs/object/omit.js"
    }
  },
  "files": [
    "dist",
    "README.md"
  ],
  "sideEffects": false
}

5. 发布后验证清单

包已出现在 npm 上
版本号正确
Git Tag 已推送
文档网站已更新（如集成 TypeDoc）
CHANGELOG.md 已包含本次变更
可通过 npm install your-package@latest 安装

结语：发布不是终点，而是承诺的开始

每一次 npm publish 都是一次对开发者的承诺：

• 稳定性：不轻易破坏现有功能
• 透明性：通过 SemVer 明确变更影响
• 可追溯性：Git Tag 让任何版本都可复现

当你遵循这套流程发布 v1.0.0 时，你不仅是在上传代码，更是在建立一个可信、可持续演进的开源项目。

真正的专业，藏在每一个细节里。 而一个严谨的发布流程，正是这种专业的最好体现。