开源项目发布前：维护者需要逐项确认什么
1. 错误的 Tag 发布会破坏下游兼容性
在开源社区维护项目，最让人心惊肉跳的时刻不是写 Bug，而是把打好的版本 Tag 推送到 GitHub 并自动发布到 npm 或 PyPI 的那一瞬间。
例如，补丁版本中删除看似未使用的导出类型，仍可能破坏下游的隐式依赖。发布前需要用 API 兼容性检查和产物验证发现这类变化。
更令人头疼的还有产物缺失问题——在本地打包时由于忽略了.npmignore配置，导致构建后的dist/index.d.ts根本没有被打进 npm 包中。开发者升级后直接报Cannot find module错误。
开源项目的交付，永远不能依赖维护者的“细心”或者“凭感觉”。必须建立一套强制性的Pre-flight Release Check（发布前预检流水线），把人为疏忽彻底阻断在发布之前。
flowchart TD Start[Trigger Release Pipeline] --> Step1[1. Clean Build & Type Check] Step1 --> Step2[2. SemVer Breaking Change Audit] Step2 --> Step3[3. Export File & d.ts Integrity Validation] Step3 --> Step4[4. Bundle Size Limit Gate] Step4 --> Step5[5. NPM Pack Dry-Run Checklist] Step5 --> Decision{All Pre-flight Checks Passed?} Decision -- No --> Abort[Abort Release / Report Error] Decision -- Yes --> TagPublish[Git Tag & NPM Publish]2. Pre-flight 检查表：从 API 契约、TypeScript 类型导出到 Bundle 校验
一个合格的开源项目交付预检，至少要穿透以下四个维度的检查：
维度一：TypeScript 类型文件完整性（Type Integrity）
使用tsc --emitDeclarationOnly编译出的.d.ts文件，必须确保其引用的外部类型路径在打包后的dist目录中真实有效。最常见的陷阱是在代码里写了相对路径import type { Foo } from '../src/types'，结果发布的.d.ts文件依然保留了这个无法被下游解析的源路径。
维度二：Package Exports 字段校验
现代 Node.js 社区普遍使用了package.json中的exports映射。必须用工具校验import（ESM）、require（CJS）以及types三条路径是否均配置妥当，并且对应的入口文件在磁盘上客观存在。
维度三：体积突变警报（Bundle Size Guard）
开源项目对打包体积极其敏感。如果一个轻量级工具库因为误引入了一个不带 Tree-shaking 的大型依赖，导致打包产物从 5KB 瞬间剧增到 120KB，这属于极其严重的交付事故。预检必须包含 Bundle 大小硬限制。
3. 自动化 SemVer Guard 与破坏性变更防御
语义化版本号（Semantic Versioning）是开源社区沟通的基石：
- PATCH（主版本.次版本.修订号，如 1.0.1）：仅包含向后兼容的 Bug 修复。
- MINOR（如 1.1.0）：包含向后兼容的新功能。
- MAJOR（如 2.0.0）：包含不兼容的 API 破坏性变更（Breaking Changes）。
维护者最容易犯的错误是在 PATCH 或 MINOR 发布里悄悄修改了既有 API 的参数签名或者返回值类型。
为了避免这种悲剧，开源项目应该引入 API 提取工具（如@microsoft/api-extractor），在每次构建时自动生成 API 声明快照文件（temp/project.api.md）。在预检阶段将当前分支的 API 声明与上一次发布的 Tag 进行 Diff 对比。如果检测到公共导出函数被删除或类型签名缩小，脚本将直接拦截发布，要求作者提升 MAJOR 版本。
4. 生产级 TypeScript/Node.js 自动化 Release 预检脚本
下面是经过开源项目生产验证的 Pre-flight Release Check 预检 CLI 脚本。在执行npm publish之前通过prepublishOnly钩子自动触发。
import fs from 'fs' import path from 'path' import { execSync } from 'child_process' export interface CheckResult { passed: boolean message: string } export class ReleasePreflightAuditor { private projectRoot: string constructor(projectRoot: string = process.cwd()) { this.projectRoot = projectRoot } // 1. 检查 package.json 的 exports 入口合法性 public checkExportsField(): CheckResult { const pkgPath = path.join(this.projectRoot, 'package.json') if (!fs.existsSync(pkgPath)) { return { passed: false, message: 'package.json 文件不存在' } } const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) const exports = pkg.exports if (!exports) { return { passed: false, message: 'package.json 缺少 "exports" 字段定义' } } // 校验 . 路径入口 const mainExport = exports['.'] || exports const pathsToCheck: string[] = [] if (typeof mainExport === 'object') { if (mainExport.import) pathsToCheck.push(mainExport.import) if (mainExport.require) pathsToCheck.push(mainExport.require) if (mainExport.types) pathsToCheck.push(mainExport.types) } for (const relPath of pathsToCheck) { const absPath = path.join(this.projectRoot, relPath) if (!fs.existsSync(absPath)) { return { passed: false, message: `Exports 指向的文件不存在: ${relPath}` } } } return { passed: true, message: 'Exports 路径完整性校验通过' } } // 2. 校验打包产物文件大小是否超标 (例如限定 50KB) public checkBundleSize(maxSizeKb: number = 50): CheckResult { const distPath = path.join(this.projectRoot, 'dist') if (!fs.existsSync(distPath)) { return { passed: false, message: 'dist 构建目录不存在，请先执行 npm run build' } } let totalSizeBytes = 0 const calcDirSize = (dir: string) => { const files = fs.readdirSync(dir) for (const file of files) { const fullPath = path.join(dir, file) const stat = fs.statSync(fullPath) if (stat.isDirectory()) { calcDirSize(fullPath) } else if (file.endsWith('.js') || file.endsWith('.mjs')) { totalSizeBytes += stat.size } } } calcDirSize(distPath) const totalKb = totalSizeBytes / 1024 if (totalKb > maxSizeKb) { return { passed: false, message: `Bundle 体积超限: 当前 ${totalKb.toFixed(2)}KB, 限制为 ${maxSizeKb}KB` } } return { passed: true, message: `Bundle 体积符合要求: ${totalKb.toFixed(2)}KB` } } // 3. 执行 Dry-run 打包模拟 public runNpmPackDryRun(): CheckResult { try { const output = execSync('npm pack --dry-run --json', { cwd: this.projectRoot, encoding: 'utf-8' }) const packInfo = JSON.parse(output) const files = packInfo[0]?.files || [] // 必须包含 README.md 和 LICENSE const fileNames = files.map((f: any) => f.path) const hasReadme = fileNames.some((name: string) => name.toLowerCase().includes('readme')) const hasLicense = fileNames.some((name: string) => name.toLowerCase().includes('license')) if (!hasReadme || !hasLicense) { return { passed: false, message: '发布的 npm 包中缺少 README.md 或 LICENSE 文件' } } return { passed: true, message: `npm pack 模拟成功，共包含 ${files.length} 个文件` } } catch (err: any) { return { passed: false, message: `npm pack 失败: ${err.message}` } } } // 运行全部检查项 public runAllChecks(): void { console.log('🚀 开始执行开源项目 Release Pre-flight 检查...\n') const checks = [ { name: 'Package Exports 路径检查', fn: () => this.checkExportsField() }, { name: 'Bundle 体积阈值检查', fn: () => this.checkBundleSize(50) }, { name: 'NPM Pack 产物模拟检查', fn: () => this.runNpmPackDryRun() } ] let hasError = false for (const check of checks) { const result = check.fn() if (result.passed) { console.log(`✅ [PASS] ${check.name}: ${result.message}`) } else { console.error(`❌ [FAIL] ${check.name}: ${result.message}`) hasError = true } } if (hasError) { console.error('\n💥 Pre-flight 预检未通过，发布已自动终止！请修复上述问题后再试。') process.exit(1) } else { console.log('\n🎉 所有 Pre-flight 检查顺利通过！允许执行发布。') } } } // 脚本直接入口触发 if (require.main === module) { const auditor = new ReleasePreflightAuditor() auditor.runAllChecks() }5. 社区协作与 Changelog 的生成治理
有了自动化的 Pre-flight 预检流水线，开源维护者才能把更多精力放回到真正的社区协作上。
最后的发布闭环是 Changelog。千万不要手动去回溯 Git 提交记录拼写 Changelog。应该要求社区贡献者在提交 PR 时使用 Conventional Commits 规范（如feat:,fix:,docs:）。在 Pre-flight 阶段使用conventional-changelog或changesets自动生成干净的变更日志。
开源项目的口碑不是靠天花乱坠的宣传，而是建立在每一次发布的稳定与严谨之上。在交付前把预检工具链落到实处，才能让项目在社区里走得更远。
