如何实现公共非作用域包的语义发布

有关利用 GitHub Actions 的强大功能使用语义发布来发布非作用域公共包的详细说明

在不断发展的软件开发环境中，保持版本一致性和自动化发布过程比以往任何时候都更加重要。进入语义发布：旨在确保清晰且结构化的版本控制的工具。对于利用公共非作用域包的开发人员来说，这个过程可能看起来令人畏惧。然而，借助触手可及的 GitHub 操作的强大功能，自动化变得轻而易举。

本文提供了详细而全面的指南，提供了将语义发布无缝集成到您的工作流程中的分步说明，专为那些使用公共非作用域包的用户量身定制。深入研究并发现软件发布的简化方法。

当我创建我的公共包，我在将其无缝发布到 NPM 时遇到了障碍。确保正确的配置是一个挑战。

为了解决这个问题，让我们逐步体验如何正确发布公共包国家公共管理。

内容概述

• 为包命名
• 创建一个包
• 包来源
• 代币
• GitHub 操作设置
• 语义发布
• 提交格式
• 发布包
• 结论

为包命名

在开始实现我们的包之前，最好先找到它的正确名称。为确保该名称尚未被占用 - 检查my_package_name并将其用作您的包。我选择了“tokky”。从那时起，保留包的名称是不可能的。对于 npm 中的名称，您必须发布包。

创建一个包

目标是开发一个简单的包，将内容输出到控制台。我们需要确保可以安装并运行它。对于构建过程，让我们使用简单的esbuild 。

在本文中，我将使用包的名称tokky 。让我们使用初始数据创建package.json 。

 mkdir tokky && cd tokky && npm init -y

执行命令后，系统为项目生成了一个默认的package.json文件，如下所示：

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

在本指南中， package.json文件在确保正确配置方面发挥着至关重要的作用。此时，让我们指定包的节点版本：

 echo "v18" > .nvmrc

并使用以下命令激活指定版本：

 nvm use

对于README.md文件：

 echo "# Tokky\n\nA simple zero dependency logger for node js." > README.md

最后，安装开发依赖项：

 npm i -D esbuild eslint prettier

在我们的初始配置中，我们需要解决package.json中的几个关键点：

• main ：指定模块的主要入口点。
• bin ：在这里，您将指定模块提供的任何可执行文件。
• files ：这应该包含一系列文件模式，这些文件模式将在打包包并随后发布到 npm 注册表时包含在内。
• private ：确保将其设置为false ，因为我们的包旨在公开。
• publishConfig ：对此的访问权限应设置为public 。

经过这些配置后，您的package.json应类似于以下内容：

 { "name": "tokky", "version": "1.0.0", "description": "Node js logger package", "main": "dist/index.js", "scripts": { "build": "esbuild src/index.js --bundle --platform=node --format=cjs --minify --outfile=dist/index.js", }, "files": [ "dist" ], "bin": { "tokky": "./dist/index.js" }, "keywords": [ "logger", "nodejs", "tokky" ], "private": false, "author": { "name": "Anton Kalik", "email": "[email protected]", "url": "https://idedy.com" }, "publishConfig": { "access": "public" }, "license": "MIT", "engines": { "node": "18.xx" }, "devDependencies": { "esbuild": "^0.19.2", "eslint": "^8.49.0", "prettier": "^3.0.3" } }

初始设置后的 package.json

另外，我们添加两个忽略文件：

 .idea node_modules dist

.gitignore

对于 npm：

 .idea /src/ /node_modules/ /test/ /.nvmrc .github/

.npmignore

最后，我将概述我的 ESLint 设置。但是，请记住，配置可能会根据包的具体要求而有所不同。

 module.exports = { env: { browser: true, commonjs: true, es2021: true, node: true, }, extends: "eslint:recommended", overrides: [ { env: { node: true, }, files: ["src/**/*.js", ".eslintrc.{js,cjs}"], parserOptions: { sourceType: "script", }, }, ], parserOptions: { ecmaVersion: "latest", }, rules: {}, };

.eslintrc.js 配置

接下来，前往 GitHub 并建立一个新的存储库。以您的包裹命名。

继续执行后续命令：

 git init git add . git commit -m "first commit" git branch -M main git remote add origin [email protected]:<your_github_username>/tokky.git git push -u origin main

包来源

接下来，让我们制作一个基本的应用程序并设置它以进行构建。在src文件夹内，生成一个index.js文件并使用以下内容填充它：

 #!/usr/bin/env node const os = require('os'); const username = os.userInfo().username; if (process.argv[2] === 'hi') { console.log(`Hello ${username}`); }

包示例的简单脚本

这个概念很简单：执行my_package_name hi应显示“Hello [username]”。

要验证此功能，请使用以下命令直接从存储库执行命令：

 node src/index.js hi

如果输出符合预期，就该构建源代码了：

 npm run build

成功运行此命令将生成一个dist文件夹，其中包含缩小的index.js文件。

代币

执行语义发布，这将确定版本碰撞并根据提交消息处理发布过程，需要环境变量（ GITHUB_TOKEN ， NPM_TOKEN ）才能正确运行。令牌是从 GitHub 机密中获取的，以确保它们的机密性。

要设置GITHUB_TOKEN ，请导航到此处： https://github.com/settings/tokens

使用下拉菜单生成令牌。单击新的个人访问令牌（经典）并如图所示设置权限。

使用您的包名称，如下所示：

生成后，复制令牌值并对其保密 - 请勿与他人共享，这一点至关重要。暂时安全地存储此令牌，因为我们很快将在语义发布 CLI 中需要它。

要生成NPM_TOKEN ，您首先需要一个帐户npm 官方网站。如果您尚未注册，请完成注册过程。之后，导航至：

 https://www.npmjs.com/settings/<your_user_name>/tokens/new

并使用“发布”选项生成“经典”令牌。

复制生成的令牌值并导航到 GitHub 机密：

 https://github.com/<your_user_name>/<your_repo_name>/settings/secrets/actions/new

并将新秘密作为NPM_TOKEN放入存储库秘密中：

现在设置了我们的机密，我们可以配置 GitHub Actions。

GitHub 操作设置

为了自动化我们的流程，我们将使用 GitHub Actions。这是集成在 GitHub 中的CI/CD工具。它允许开发人员直接从其 GitHub 存储库自动化工作流程，例如构建、测试和部署应用程序。通过在 YAML 文件中定义工作流程，用户可以根据特定事件（例如推送和拉取请求或计划时间）触发操作，从而使软件开发过程更加高效和自动化。

首先，在项目的根目录下创建一个.github目录。在此目录中，建立一个workflows子文件夹。

在这里，制作名为release.yml的配置文件并使用以下内容填充它：

 name: Release package on: push: branches: - main jobs: release: runs-on: ubuntu-latest if: ${{ github.ref == 'refs/heads/main' }} steps: - name: Checkout uses: actions/checkout@v3 - name: Set up Node.js uses: actions/setup-node@v3 with: node-version: "18" - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Semantic Release run: npm run semantic-release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

此工作流触发主分支的推送事件。它配置为在 GitHub 提供的最新 Ubuntu 虚拟机上运行该作业。虽然不必深入研究每项工作，但让我们重点关注一些特定的工作。最后，请注意我们如何使用指定的标记调用npm run semantic-release 。

语义发布

对于自动化发布过程，我们将使用语义发布。该工具根据提交消息语义处理版本控制和包发布。它遵循语义版本控制 (SemVer) 的约定来确定版本升级（主要、次要或补丁）。通过分析提交消息，它消除了版本控制的手动步骤，确保版本号一致，并简化了发布过程。我们来设置一下吧。

对于该设置，我们将使用这个 GitHub 代码并在您的存储库上运行它：

 npx semantic-release-cli setup

并遵循以下问题：

 % npx semantic-release-cli setup ? What is your npm registry? https://registry.npmjs.org/ ? What is your npm username? your_user_name ? What is your npm password? [hidden] ? What is your NPM two-factor authentication code? 00000000 ? Provide a GitHub Personal Access Token (create a token at https://github.com/s ettings/tokens/new?scopes=repo) ghp_your_token_here ? What CI are you using? Github Actions

您应该已经拥有您的个人令牌。只需在出现提示时输入即可。同样，我们设置的 GitHub Actions 将利用我们之前在存储库机密中建立的NPM_TOKEN 。如果您现在检查package.json ，版本将显示为：

 "version": "0.0.0-development",

和新脚本：

 "semantic-release": "semantic-release"

它是由语义发布 CLI 自动生成的。我们需要按如下方式增强此脚本：

 "semantic-release": "semantic-release --branches main"

这表明版本只会从主分支进行。

此外，语义发布会根据package.json中的repository字段生成描述。该字段提供有关包源代码位置的详细信息。

 "repository": { "type": "git", "url": "https://github.com/<your_github_username>/your_github_repo.git" }

现在，让我们通过以下方式推动所有更改：

 git add . && git commit -m "semantic release" && git push

提交格式

语义发布依赖于结构化提交消息的约定来确定版本碰撞的类型（主要、次要或补丁）并生成更改日志。这种提交约定通常称为“常规提交”格式。

对于此配置，我们需要几个插件。确保您的package.json包含以下内容：

 "release": { "branches": [ { "name": "main" } ], "plugins": [ [ "@semantic-release/commit-analyzer", { "releaseRules": [ { "type": "feat", "release": "minor" }, { "type": "fix", "release": "patch" }, { "type": "refactor", "release": "patch" }, { "type": "build", "release": "patch" }, { "type": "chore", "release": "patch" }, { "type": "minor", "release": "patch" } ] } ], "@semantic-release/release-notes-generator", "@semantic-release/npm", "@semantic-release/github", [ "@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" } ] ] }

包.json

对于设置提交格式工具，我们将使用承诺。要安装它，请执行以下命令：

 npx commitizen init cz-conventional-changelog --save-dev --save-exact

该命令将需要几分钟的时间。然后使用新脚本更新package.json ：

 "scripts": { // ... "commit": "cz" },

现在是使用该脚本的时候了。首先执行git add . ，然后运行npm run commit并提供提交所需的详细信息。

看起来是这样的：

 ? Select the type of change that you're committing: feat: A new feature ? What is the scope of this change (eg component or file name): (press enter to skip) commit ? Write a short, imperative tense description of the change (max 86 chars): (14) add commitizen ? Provide a longer description of the change: (press enter to skip) ? Are there any breaking changes? No ? Does this change affect any open issues? No

之后，执行git push 。

在 GitHub 操作中，您将看到我们的提交失败，因为我们尚未安装用于自动提交消息过程的其余软件包。

 npm i -D @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/npm @semantic-release/changelog

在大多数参考文献中经常被忽视的一个关键步骤是设置工作流权限。导航到https://github.com/<your_user_name>/tokky/settings/actions并配置权限以允许 GitHub 操作读取和写入。

接下来，让我们稍微改变一下。使用特定关键字feat:进行提交，后跟您的消息。

 git add . && git commit -m "feat: my feature commit" && git push

您还记得package.json中的releaseRules吗？这些规则规定了我们如何增加软件包版本的版本。完成此操作后，您可以使用特定关键字（例如feat 、 fix 、 refactor等）创建拉取请求。一旦该拉取请求被批准并随后合并到主分支中，它将启动一个触发器。然后，此触发器会激活 GitHub 操作，自动执行发布过程，并确保您的包无缝更新。

发布包

该包已成功发布，整个过程已实现自动化以提高效率。要确认发布，请前往您的 npm 设置https://www.npmjs.com/settings/<your_user_name>/packages并查看软件包部分；在那里，您将找到新发布的包。

现在，通过像npx your_package_name hi这样的简单命令，您可以立即看到我们开发测试的结果。此外，可以使用命令npm i -g your_package_name全局安装该包。

结论

正如我们在本文中所看到的，虽然初始设置可能充满挑战，但回报在于建立简化且一致的发布流程。利用 GitHub Actions 可以简化这些复杂性，确保开发人员可以专注于代码质量而不是复杂的逻辑问题。

无论您是刚刚开始使用公共包还是在发布工作中遇到了挫折，采用结构化、自动化的工作流程都有不可否认的价值。通过集成语义发布，您可以确保一致的版本控制并倡导面向未来的软件开发方法。

这是为了实现无缝发布，减少麻烦，并花更多时间完善代码，推动我们的数字世界向前发展。

请记住，在 GitHub Actions 中为NPM_TOKEN和GITHUB_TOKEN授予适当的权限至关重要。此外，您的package.json应使用publishConfig访问设置正确配置，并确保private配置设置为false 。如果您遇到任何问题或有任何见解，请随时发表评论。

参考

存储库： https://github.com/antonkalik/tokky
语义发布 CLI： https://github.com/semantic-release/cli
承诺： https://github.com/commitizen/cz-cli