# 发布 JSR 包

JSR 面向现代 ESM 包，鼓励直接发布 TypeScript 源码并生成 API 文档。JSR 包可以被 Deno、Node.js 和其他工具消费。

## 最小包配置

```json title="deno.json"
{
  "name": "@scope/greet",
  "version": "1.0.0",
  "exports": {
    ".": "./mod.ts",
    "./testing": "./testing.ts"
  },
  "publish": {
    "exclude": ["coverage", "*.snap"]
  }
}
```

JSR 只发布 ESM；文件名必须兼容 Windows/Unix，跨文件导入在发布时必须可解析。公开 API 避免 slow types，以改善类型检查、文档与 Node 兼容性。

## 发布前验证

```bash
deno fmt --check
deno lint
deno check mod.ts
deno test
deno publish --dry-run
```

`--dry-run` 会列出实际上传文件并执行发布校验。版本发布后不可修改或删除；严重问题版本使用 yank，废弃项目使用 archive。

## GitHub Actions OIDC

先在 JSR 包设置中关联 GitHub 仓库，再允许 workflow 获取 OIDC token：

```yaml title=".github/workflows/publish.yml"
name: publish
on:
  push:
    tags: ["v*"]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v7
      - uses: denoland/setup-deno@v2
        with:
          deno-version: v2.x
      - run: deno publish
```

OIDC 不需要长期发布 token，并生成 provenance attestation。其他 CI 可用 `--token`，但官方文档明确说明 token 发布不生成 provenance。

<Callout type="warn" title="发布是外部不可逆动作">
运行 `deno publish` 前确认 scope、版本、tag、变更日志和实际文件列表。Agent 不应把 dry run 的成功视为获得发布授权。
</Callout>

官方依据：[Publishing packages](https://jsr.io/docs/publishing-packages)、[Package configuration](https://jsr.io/docs/package-configuration)、[Packages and versions](https://jsr.io/docs/packages)。