包 - 文档 - JSR 中文

包是 JSR 的核心。包是作者发布到 JSR 网站上的 JavaScript 或 TypeScript 代码集合。其他用户可以使用 `jsr:` 导入来导入包。了解有关使用 JSR 的更多信息。

包由范围包含。范围是作者发布到 JSR 网站上的包集合。范围类似于 npm 组织或 GitHub 帐户。了解有关范围的更多信息。

包具有名称。包名称在一个范围内是唯一的 - 同一个范围内不能有两个包具有相同的名称。包名称必须在 2 到 20 个字符之间，并且只能包含小写字母、数字和连字符。它们不能以连字符开头。

包可以在 jsr.io/new 创建。包始终在范围内创建，因此必须先创建范围才能创建包。

描述

包可以有描述。描述是关于包的简短介绍，显示在包页面和搜索结果中。描述应该为潜在用户概括包的功能。描述最多可以包含 250 个字符。可以在包页面的“设置”选项卡中更新描述。

运行时兼容性

包可以指定它们与哪些运行时兼容。这对包使用者很有用，他们可以一目了然地看到包支持哪些运行时。此信息显示在包页面和搜索结果中。对于 5 个支持的运行时（Deno、Node.js、Cloudflare Workers、Bun 和 Web 浏览器），每个包都可以指定“支持”、“不支持”或“未知支持”的支持级别。未知支持意味着包作者不知道包是否与运行时兼容。可以在包页面的“设置”选项卡中更新兼容性。

链接的 GitHub 仓库

包可以有链接的 GitHub 仓库。此仓库显示给包的使用者，可用于链接到包的源代码和问题跟踪器。

包页面上显示的 GitHub 仓库由 JSR 验证为由包作者管理。这可以防止包作者链接到他们不拥有的仓库。

可以在包页面上的“设置”选项卡中将 GitHub 仓库链接到包。只有范围管理员可以将 GitHub 仓库链接到包。范围管理员也可以在同一页面上取消链接 GitHub 仓库。要链接仓库，必须是 GitHub 上该仓库的管理员。

链接 GitHub 仓库还可以使用 OIDC 从 GitHub Actions 启用无令牌发布。了解有关从 GitHub Actions 发布的更多信息。

删除包

可以在包页面上的“设置”选项卡中删除包。只有范围管理员可以删除包。

只有在包没有发布版本的情况下才能删除包。如果包有发布版本，则无法删除。了解有关注册表不变性的更多信息。

版本

包中的代码以版本的形式发布。版本是包代码在某个时间点的快照。版本是不可变的 - 一旦发布版本，就不能更改或删除。这确保了包的可靠性，并且用户可以相信包不会在他们不知情的情况下发生变化。了解有关注册表不变性的更多信息。

版本使用 jsr publish 或 deno publish 命令发布。了解有关发布包的更多信息。

版本必须是有效的 SemVer 版本。我们建议包遵循语义版本控制策略。这些策略如下

如果您进行重大更改，请增加主版本号。
如果您以向后兼容的方式添加功能，请增加次版本号。
如果您以向后兼容的方式修复错误，请增加修订版本号。

要发布新版本的包，您必须在运行jsr publish或deno publish之前，在您的配置文件中更新版本号。

撤回版本

包版本无法删除。但是，有时您可能希望阻止用户使用特定版本的包，例如，因为该版本包含严重错误。在这种情况下，您可以“撤回”该版本。

撤回版本会执行以下操作：

在解析依赖项时，Semver 解析会忽略该版本。
在包页面上显示一条警告，说明该版本已被撤回。
阻止该版本在搜索结果中显示。
在包的版本列表中将该版本标记为已撤回。
在确定包的最新版本时，不会考虑已撤回的版本。

撤回版本不会阻止用户显式下载该版本、查看文档或查看源代码。特别是，如果用户已经下载了该版本，将其包含在他们的锁定文件中，或在他们的导入中显式指定了该版本，他们仍然可以使用它。

要撤回版本，请转到包页面上的“版本”选项卡，然后单击要撤回的版本旁边的“撤回”按钮。只有范围管理员可以撤回版本。可以通过单击同一页面上版本旁边的“取消撤回”按钮来取消撤回版本。

为了说明删除和撤回版本之间的区别，请考虑以下场景：

您发布了包的版本1.0.0。
您发布了包的版本1.0.1。
您在版本1.0.1中发现了一个严重错误，并希望阻止用户使用它。
您撤回了版本1.0.1。

此时，如果用户已经下载了版本1.0.1，或者在他们的导入中显式指定了该版本，例如：

import { foo } from "jsr:[email protected]";

但是，如果用户没有下载版本1.0.1，并且没有在他们的导入中显式指定该版本，他们将获得版本1.0.0，用于以下导入：

import { foo } from "jsr:foo@1";

文档

包的文档是自动从包的源代码生成的。使用 JSDoc 注释为包中所有导出的函数、类和变量生成文档。

JSR 使用 deno doc 生成文档。这意味着，可以通过在本地运行 deno doc --html 来预览包的文档在 JSR 上的显示效果。这将生成 HTML 文件，其文档外观与 JSR 网站上显示的非常相似。

包页面上的“概述”选项卡显示了包的默认入口点的模块文档。如果包没有默认入口点，或者默认入口点没有模块文档，则“概述”选项卡将显示包的 README。如果不存在 README，则“概述”选项卡将仅在侧边栏中显示包的结构。

包页面底部侧边栏包含指向包的默认入口点的所有导出以及包中所有其他入口点的链接。单击这些链接将显示所选特定符号或入口点的文档。

为包提供有用且相关的文档对于使其成功至关重要。用户通常会在决定使用某个包之前查看其文档。我们建议您为包中的所有导出函数、类和变量编写文档。了解有关编写文档的更多信息.

发布

使用 jsr publish 或 deno publish 命令发布包。了解更多关于发布包的信息.

包页面上的“发布”选项卡包含有关发布包的有用信息，例如配置文件的概述以及从 GitHub Actions 发布的说明。