管理 Go 模块

本页面介绍了如何管理存储在 Artifact Registry 中的打包 Go 模块。

准备工作

1. 如果目标代码库不存在，请创建新代码库。选择 Go 作为代码库格式。
2. 验证您是否拥有访问代码库所需的权限。
3. （可选）为 gcloud 命令配置默认值。
4. 安装 Go 1.15 或更高版本。

5. 安装 package-go-module gcloud CLI 加载项：

   gcloud components install package-go-module

6. 配置 Go 以通过 Artifact Registry 进行身份验证。

注意： Artifact Registry 不支持 Go 模块 -tool 标志。

所需的角色

如需获得管理模块所需的权限，请让管理员向您授予代码库的以下 IAM 角色：

• 查看模块： Artifact Registry Reader (roles/artifactregistry.reader)
• 下载或安装模块： Artifact Registry Reader (roles/artifactregistry.reader)
• 向代码库添加模块： Artifact Registry Writer (roles/artifactregistry.writer)
• 删除模块： Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

上传模块

代码库模式：标准

如需将模块打包并上传到代码库，请运行以下命令：

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

替换以下内容：

• 将 PROJECT 替换为您的 Google Cloud项目 ID。
• 将 REPOSITORY 替换为存储相应软件包的代码库的名称。
• LOCATION 替换为代码库的单区域或多区域位置。
• 将 MODULE_PATH 替换为模块路径。例如：example.com/foo 如需了解详情，请参阅 Go 模块参考。
• VERSION，其中包含模块的语义化版本（格式为 vX.Y.Z，其中 X 是主要版本，Y 是次要版本，Z 是补丁程序版本）。
• 将 SOURCE_LOCATION 替换为 Go 模块根目录的路径。如果您省略 --source 标志，则默认值为当前目录。

模块已上传到 Artifact Registry。

如需详细了解如何创建 Go 模块，请参阅此教程。

上传新的模块版本

代码库模式：标准

如需在配置默认值时将模块的新版本上传到默认项目、代码库和位置，请运行以下命令并指定新版本号：

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

将 VERSION 替换为更新后模块的版本。例如，如需上传路径为 example.com/foo 的模块的版本 0.1.1，请运行以下命令：

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v0.1.1 \
      --source=SOURCE_LOCATION

如需将模块标记为预发布版本，请在 VERSION 后面添加短划线，然后附加模块的预发布标识符：

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION-PRE_RELEASE_IDENTIFIERS \
      --source=SOURCE_LOCATION

将 PRE_RELEASE_IDENTIFIERS 替换为以英文句点分隔的 ASCII 字母数字字符和连字符。例如，如需上传路径为 example.com/foo、由 alpha.x.12m.5 标识的模块的预发布版本，请运行以下命令：

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v1.0.0-alpha.x.12m.5 \
      --source=SOURCE_LOCATION

注意： 预发布标识符必须是英文句点分隔的 ASCII 字母数字字符和连字符。不支持元数据。如需详细了解版本控制，请参阅语义版本控制 2.0.0 和这篇博文，了解 Go 特有的详细信息。

上传新的主要版本

代码库模式：标准

主要版本不向后兼容之前的版本。为防止用户导入重大更改，v1 之后的主要版本必须具有与之前版本不同的模块路径。从 v2开始，主要版本会添加到模块路径的末尾。

例如，example.com/foo 的 v2.0.0 的模块路径为 example.com/foo/v2。

建议的最佳实践是在 v1 之后开发主要版本，并将这些版本放在以其主要版本后缀命名的单独目录中。

如需在配置默认值时将路径为 example.com/foo 的模块的新主要版本 2.0.0 上传到默认项目、代码库和位置，请运行以下命令：

  gcloud artifacts go upload --module-path=example.com/foo/v2 --version=v2.0.0

列出模块

代码库模式：标准、远程、虚拟

如需在配置默认值时检查默认项目、代码库和位置中的已上传 Go 模块，请运行以下命令：

  gcloud artifacts packages list

输出将如下所示：

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

查看模块版本详情

代码库模式：标准、远程、虚拟

如需在配置默认值时查看默认项目、代码库和位置中模块的版本，请运行以下命令：

  gcloud artifacts versions list --package=MODULE_PATH

输出将如下所示：

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

将模块用作依赖项

代码库模式：标准、远程、虚拟

如需导入存储在 Artifact Registry 中的模块，您需要指示 Go 从 Artifact Registry 中查找依赖项并绕过校验和数据库。按照为 Go 设置身份验证中的说明设置身份验证和 Go 环境。

1. 如果您使用短期凭据向 Artifact Registry 进行身份验证，则必须运行以下命令来刷新 OAuth 令牌：

     GOPROXY=proxy.golang.org \
     go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@latest refresh
   

2. 如果您的模块还没有 go.mod 文件，请将目录更改为模块的文件夹，然后运行 go mod init 为您的软件包创建 go.mod 文件。

     go mod init MODULE_PATH
   

   将 MODULE_PATH 替换为存储在 Artifact Registry 中的模块的模块路径。如需了解详情，请参阅 Go 模块参考。

3. 如需要求使用存储在 Artifact Registry 中的模块版本，请修改 go.mod 文件，使其类似于以下内容：

   
   module example.com/bar
   
   go 1.19
   
   require example.com/foo v0.1.0
   

   替换以下内容：

   • example.com/foo 是所需模块的模块路径
   • v0.1.0 是存储在 Artifact Registry 中的版本

4. 在 main.go 文件的 import 部分中正常添加模块路径。

   例如，如需导入存储在 Artifact Registry 中的路径为 example.com/foo 的模块，您的导入部分可能类似于以下内容：

     
     package main
   
     import (
       foo "example.com/foo"
     )
   
     func main() {
   
       ...
   
     }
   
     
   

5. 运行 go mod tidy 以下载依赖项：

     go mod tidy
   

6. 正常运行模块：

     go run .
   

   存储在 Artifact Registry 中的模块会被下载并用作依赖项。

删除打包的 Go 模块

代码库模式：标准、远程

您可以删除软件包及其所有版本，也可以删除特定版本。

• 删除软件包后，您无法撤消此操作。

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

1. Open the Repositories page in the Google Cloud console.

   打开“代码库”页面

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Select the package that you want to delete.

4. Click DELETE.

5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Replace the following:

• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

1. Open the Repositories page in the Google Cloud console.

   打开“代码库”页面

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Click a package to view versions of that package.

4. Select versions that you want to delete.

5. Click DELETE.

6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Replace the following:

• VERSION is the name of the version to delete.
• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

后续步骤

• 不妨试试 Go 快速入门。
• 下载与模块或版本关联的单个文件，而无需使用 Go 命令。