Frontend Academy · 课时

版本管理与发布到 npm

使用语义化版本控制，通过 Changesets 或 standard-version 自动生成变更日志，并将库发布到 npm 或私有仓库。

第 3 / 4 课15 个步骤

版本管理与发布到 npm 是 CoddyKit 上的免费 Frontend Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Frontend Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Frontend Academy 课程共包含 4 节课。

为什么发布到 npm

如果您的设计系统被多个应用使用，就应将其发布为软件包。使用者通过 npm/yarn/pnpm 安装、锁定版本，并按照自己的计划更新。

语义化版本（SemVer）

版本遵循 MAJOR.MINOR.PATCH。MAJOR：不兼容的更改。MINOR：新功能，向后兼容。PATCH：仅修复错误。

何时提升版本号

重命名了属性？MAJOR。添加了新的可选属性？MINOR。修复了 CSS 错误？PATCH。1.0 之前的版本（0.x.y）可能在 MINOR 版本中引入不兼容更改——但请尽量保持克制。

package.json——清单文件

配置软件包在 npm 上的呈现方式。

{
  "name": "@yourorg/design-system",
  "version": "1.4.2",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": { "import": "./dist/index.esm.js", "require": "./dist/index.cjs.js" },
    "./theme": "./dist/theme.js"
  },
  "files": ["dist", "README.md"],
  "peerDependencies": { "react": "^18.0.0" }
}

构建输出

发布 CommonJS、ESM 和类型声明。tsup 或 vite build --lib 等工具可以处理这些内容。

// tsup.config.ts
export default {
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  clean: true,
  external: ['react', 'react-dom']
};

// package.json: "build": "tsup"

peerDependencies

将 React/Vue 等列为 peerDependencies，这样使用者可以使用自己的版本。将它们标记为常规依赖会导致它们被打包两次，从而破坏钩子和上下文。

利于摇树优化

使用 ESM 导出并避免副作用，以便打包工具删除未使用的组件。在 package.json 中标记："sideEffects": false（或列出 CSS 等特定文件）。

发布到 npm

登录一次，然后发布。

npm login

# Bump version + publish:
npm version patch   # 1.4.2 -> 1.4.3
npm publish

# Or scoped public package:
npm publish --access public

使用 Changesets 自动发布

Changesets 是用于单体仓库和库发布的现代工具包。拉取请求中包含一个描述更改的“changeset”文件；发布持续集成流程会提升版本号并完成发布。

npm install -D @changesets/cli
npx changeset init

# In each PR:
npx changeset
# pick package, type (major/minor/patch), describe change
# commits .changeset/<random>.md

# CI on main:
npx changeset version  # bumps versions in package.json + generates changelog
npx changeset publish  # publishes to npm

自动生成更新日志

Changesets 会根据 changeset 描述为每个软件包自动生成 CHANGELOG.md，使用者可以查看每个版本有哪些变化。

npm 分发标签

使用分发标签发布预发行版本：npm publish --tag beta 会在不覆盖 latest 的情况下发布。使用者可以通过 npm install @yourorg/design-system@beta 主动采用该版本。

私有注册表

内部软件包可以使用 GitHub Packages、GitLab Package Registry 或自行托管的 Verdaccio。使用 .npmrc 配置：@yourorg:registry=https://npm.pkg.github.com。

弃用旧版本

将某个版本标记为已弃用，以便向安装者发出警告。

npm deprecate @yourorg/design-system@1.0.0 'Use 2.x for React 18 support'

快速检查

如果重命名了导出组件的属性，需要提升哪一种 SemVer 版本号？

在交互式课程中回答

回顾：版本管理与发布

SemVer：MAJOR.MINOR.PATCH——分别表示不兼容更改、功能和修复。构建 CJS + ESM + 类型（tsup、vite --lib）。将 React/Vue 作为 peerDependencies。使用 sideEffects:false 支持摇树优化。使用 npm publish 发布，或通过 Changesets 自动化发布。自动生成 CHANGELOG。使用分发标签发布 beta 版本。使用私有注册表管理内部软件包。

免费开始

用 AI 导师学习 HTML — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程: 41
课程: 163

免费开始学习查看完整课程

常见问题解答

「版本管理与发布到 npm」课时是免费的吗？

是的 — 「版本管理与发布到 npm」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Frontend Academy 课程的其余内容，请升级到 CoddyKit PRO。 Frontend Academy 课程共包含 4 节课。

「版本管理与发布到 npm」这节课中我会学到什么？

使用语义化版本控制，通过 Changesets 或 standard-version 自动生成变更日志，并将库发布到 npm 或私有仓库。你通过在浏览器中直接运行的动手代码来练习 Frontend Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Frontend Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Frontend Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「版本管理与发布到 npm」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Frontend Academy 课中编写并运行代码吗？

能。每节 Frontend Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Frontend Academy