有关利用 GitHub Actions 的强大功能使用语义发布来发布非作用域公共包的详细说明 在不断发展的软件开发环境中，保持版本一致性和自动化发布过程比以往任何时候都更加重要。进入 ：旨在确保清晰且结构化的版本控制的工具。对于利用公共非作用域包的开发人员来说，这个过程可能看起来令人畏惧。然而，借助触手可及的 GitHub 操作的强大功能，自动化变得轻而易举。 语义发布 本文提供了详细而全面的指南，提供了将语义发布无缝集成到您的工作流程中的分步说明，专为那些使用公共非作用域包的用户量身定制。深入研究并发现软件发布的简化方法。 当我创建我的 ，我在将其无缝发布到 NPM 时遇到了障碍。确保正确的配置是一个挑战。 公共包 为了解决这个问题，让我们逐步体验如何正确发布公共包 。 国家公共管理 内容概述 为包命名 创建一个包 包来源 代币 GitHub 操作设置 语义发布 提交格式 发布包 结论 为包命名 在开始实现我们的包之前，最好先找到它的正确名称。为确保该名称尚未被占用 - 检查 并将其用作您的包。我选择了“tokky”。从那时起，保留包的名称是不可能的。对于 npm 中的名称，您必须发布包。 my_package_name 创建一个包 目标是开发一个简单的包，将内容输出到控制台。我们需要确保可以安装并运行它。对于构建过程，让我们使用简单的 。 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 ：这应该包含一系列文件模式，这些文件模式将在打包包并随后发布到 npm 注册表时包含在内。 files ：确保将其设置为 ，因为我们的包旨在公开。 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": "antonkalik@gmail.com", "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 git@github.com:<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}`); } 包示例的简单脚本 这个概念很简单：执行 应显示“Hello [username]”。 my_package_name hi 要验证此功能，请使用以下命令直接从存储库执行命令： node src/index.js hi 如果输出符合预期，就该构建源代码了： npm run build 成功运行此命令将生成一个 文件夹，其中包含缩小的 文件。 dist index.js 代币 执行语义发布，这将确定版本碰撞并根据提交消息处理发布过程，需要环境变量（ ， ）才能正确运行。令牌是从 GitHub 机密中获取的，以确保它们的机密性。 GITHUB_TOKEN NPM_TOKEN 要设置 ，请导航到此处： 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 中的 工具。它允许开发人员直接从其 GitHub 存储库自动化工作流程，例如构建、测试和部署应用程序。通过在 YAML 文件中定义工作流程，用户可以根据特定事件（例如推送和拉取请求或计划时间）触发操作，从而使软件开发过程更加高效和自动化。 CI/CD 首先，在项目的根目录下创建一个 目录。在此目录中，建立一个 子文件夹。 .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 导航到 并配置权限以允许 GitHub 操作读取和写入。 在大多数参考文献中经常被忽视的一个关键步骤是设置工作流权限。 https://github.com/<your_user_name>/tokky/settings/actions 接下来，让我们稍微改变一下。使用特定关键字 进行提交，后跟您的消息。 feat: git add . && git commit -m "feat: my feature commit" && git push 您还记得 中的 吗？这些规则规定了我们如何增加软件包版本的版本。完成此操作后，您可以使用特定关键字（例如 、 、 等）创建拉取请求。一旦该拉取请求被批准并随后合并到主分支中，它将启动一个触发器。然后，此触发器会激活 GitHub 操作，自动执行发布过程，并确保您的包无缝更新。 package.json releaseRules feat fix refactor 发布包 该包已成功发布，整个过程已实现自动化以提高效率。要确认发布，请前往您的 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 参考 存储库： 语义发布 CLI： 承诺： https://github.com/antonkalik/tokky https://github.com/semantic-release/cli https://github.com/commitizen/cz-cli 也发布 。 在这里 谢谢 哈珀周日 主图来自 Unsplash。
