如何构建一个支持语义化版本的前端包发布流程？

前端包的规范发布是团队协作和依赖管理的基础，语义化版本通过明确的版本号规则，让使用者能快速判断版本更新是否包含破坏性变更、新功能或者问题修复。构建支持语义化版本的前端包发布流程，需要覆盖版本规则定义、版本号自动更新、发布校验、自动化执行等多个环节。

语义化版本核心规则

语义化版本号格式为主版本号.次版本号.修订号，即MAJOR.MINOR.PATCH，每个部分的变更对应不同的更新类型：

• 主版本号（MAJOR）：当做了不兼容的API修改时递增，比如删除了原有导出方法、修改了参数格式
• 次版本号（MINOR）：当做了向下兼容的功能性新增时递增，比如新增了可选配置项、新增了导出方法
• 修订号（PATCH）：当做了向下兼容的问题修复时递增，比如修复了某个场景下的报错、优化了内部逻辑

此外还可以添加预发布版本标识，比如1.0.0-alpha.1、1.0.0-beta.2，用于测试版本的发布。

基础环境准备

首先需要确保本地已经安装Node.js环境，以及包管理工具npm或者yarn，同时需要有一个可发布的前端包项目，项目的package.json中需要配置正确的name、version、main、files等基础字段。如果是发布到私有npm仓库，还需要提前配置好仓库地址。

配置版本管理相关依赖

我们可以借助成熟的工具来自动处理语义化版本的更新和发布流程，常用的工具包括standard-version用于自动生成版本号和变更日志，husky用于git钩子管理，lint-staged用于提交前校验。首先安装依赖：

npm install standard-version husky lint-staged --save-dev

配置package.json核心字段

首先需要在package.json中完善发布相关的配置，示例如下：

{
  "name": "my-frontend-package",
  "version": "0.0.0",
  "description": "一个测试用的前端包",
  "main": "dist/index.js",
  "files": ["dist"],
  "scripts": {
    "test": "jest",
    "build": "webpack --config webpack.config.js",
    "release:patch": "standard-version --release-as patch",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major",
    "release:pre": "standard-version --prerelease alpha",
    "publish": "npm publish"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.js": ["eslint --fix", "git add"]
  }
}

配置standard-version自定义规则

在项目根目录创建.versionrc文件，用于自定义版本更新和变更日志生成的规则，示例配置如下：

{
  "types": [
    {"type": "feat", "section": "新功能"},
    {"type": "fix", "section": "问题修复"},
    {"type": "break", "section": "破坏性变更"},
    {"type": "docs", "section": "文档更新", "hidden": false},
    {"type": "chore", "section": "构建流程", "hidden": false}
  ],
  "commitUrlFormat": "https://github.com/your-repo/my-frontend-package/commit/{{hash}}",
  "issueUrlFormat": "https://github.com/your-repo/my-frontend-package/issues/{{id}}"
}

编写自动化发布脚本

为了进一步简化发布流程，我们可以编写一个统一的发布脚本，自动执行构建、测试、版本更新、标签打点、推送、发布到仓库的完整流程。在项目根目录创建scripts/release.js文件：

const { execSync } = require('child_process');
const path = require('path');
const fs = require('fs');

// 获取发布类型，默认是patch
const releaseType = process.argv[2] || 'patch';
// 支持的发布类型
const validTypes = ['major', 'minor', 'patch', 'pre'];

if (!validTypes.includes(releaseType)) {
  console.error('无效的发布类型，支持的类型：major, minor, patch, pre');
  process.exit(1);
}

try {
  // 执行构建
  console.log('开始执行构建...');
  execSync('npm run build', { stdio: 'inherit' });

  // 执行测试
  console.log('开始执行测试...');
  execSync('npm run test', { stdio: 'inherit' });

  // 更新版本号和生成变更日志
  console.log(`开始更新${releaseType}版本...`);
  if (releaseType === 'pre') {
    execSync('npm run release:pre', { stdio: 'inherit' });
  } else {
    execSync(`npm run release:${releaseType}`, { stdio: 'inherit' });
  }

  // 推送代码和标签到远程仓库
  console.log('推送代码和标签到远程仓库...');
  execSync('git push --follow-tags origin main', { stdio: 'inherit' });

  // 发布到npm仓库
  console.log('开始发布到npm仓库...');
  execSync('npm run publish', { stdio: 'inherit' });

  console.log('发布流程执行完成');
} catch (err) {
  console.error('发布流程执行失败：', err.message);
  process.exit(1);
}

完整发布流程执行步骤

完成上述配置后，完整的发布流程如下：

1. 确保当前代码已经合并到主分支，并且所有改动都已经提交
2. 打开终端执行对应类型的发布命令：
   • 修复问题发布修订版本：node scripts/release.js patch
   • 新增功能发布次版本：node scripts/release.js minor
   • 破坏性变更发布主版本：node scripts/release.js major
   • 发布预测试版本：node scripts/release.js pre
3. 脚本会自动执行构建、测试、版本号更新、变更日志生成、代码推送、包发布全流程
4. 发布完成后可以在npm仓库查看对应的包版本，同时可以在git仓库看到自动生成的版本标签和变更日志

注意事项

• 发布前需要确保npm的登录状态正常，执行npm whoami可以查看当前登录用户
• 如果是发布到私有仓库，需要提前通过npm config set registry 你的仓库地址配置仓库地址
• 预发布版本不会自动提升正式版本号，需要之后再执行正式版本的发布命令来转正
• 建议在CI/CD流水线中集成该发布流程，通过分支合并或者手动触发的方式来执行，避免本地环境差异导致的问题

前端包发布语义化版本package_jsonnpm_script版本管理修改时间：2026-06-27 07:06:36