根本原因是目标仓库不支持oci artifact或未指定--manifest-type；helm chart需显式声明application/vnd.cncf.helm.chart.layer.v1+tar类型，且必须为helm package生成的.tgz文件，否则oras按默认镜像类型解析失败。
oras push 为什么报错 “failed to resolve reference”
根本原因通常是目标仓库不支持 OCI Artifact，或 oras 没指定正确的 --manifest-type。Helm chart 本身不是标准 OCI image，必须显式声明为 artifact 类型，否则 oras 默认按 application/vnd.oci.image.manifest.v1+json 尝试解析，而 Helm chart 的 index.yaml 或 Chart.yaml 不符合该结构，直接失败。
- 确认 registry 支持 OCI Artifact：Harbor ≥ 2.8、GitHub Container Registry、Azure Container Registry 都可以；Docker Hub 不支持
- 推送前必须用
oras push --manifest-type application/vnd.cncf.helm.chart.layer.v1+tar显式指定 Helm 层类型，不能省略 - 确保本地 chart 已打包为
.tgz文件（用helm package生成），oras不接受目录直推 - 错误信息如
failed to resolve reference: unexpected media type ""就是没设--manifest-type的典型表现
如何把 Helm chart 正确打包并推送到 Harbor
关键在两步：先生成合规的 .tgz，再用匹配的 media type 推送。Harbor 对 artifact 的校验比普通镜像更严格，media type 必须与内容一致，否则拉取时 helm pull 会拒绝解析。
- 用
helm package mychart/生成mychart-0.1.0.tgz，不要手动 tar 或改后缀 - 推送命令示例：
oras push myharbor.example.com/project/mychart:0.1.0 mychart-0.1.0.tgz --manifest-type application/vnd.cncf.helm.chart.layer.v1+tar - 如果 Harbor 启用了项目级权限，确保 token 或用户名密码有
push权限，否则报unauthorized: authentication required - 推送后可在 Harbor UI 的“Artifacts”标签页看到类型为
Helm Chart的条目，而非Image
helm pull 能否直接拉取 oras 推送的 artifact
可以，但依赖 Helm CLI 版本和 registry 配置。Helm v3.8+ 原生支持从 OCI registry 拉取 chart，但必须用完整 OCI 地址格式，且 registry 必须返回正确的 Content-Type 头。
- 拉取命令：
helm pull oci://myharbor.example.com/project/mychart --version 0.1.0（注意是oci://前缀） - 若报
failed to do request: Head "https://.../v2/.../blobs/...": dial tcp: lookup ...: no such host，大概率是helm解析 registry 地址失败，检查是否漏了协议或拼写错误 - Harbor 需开启
content-trust或至少允许非签名 artifact，否则某些版本 Helm 会静默跳过 -
helm show values和helm install对 OCI 源的行为与传统 repo 一致，无需额外插件
替代方案：用 helm chart repo vs oras 推送的取舍
OCI 方式更适合作为 CI/CD 流水线中的一环，尤其当团队已统一使用 Harbor 或 ACR；但若只是内部快速共享，传统 helm serve 或 GitHub Pages + helm repo index 更轻量。
- oras 推送后无法通过
helm search repo发现，必须知道确切地址，缺少索引发现能力 - CI 中自动打 tag 并推送 OCI 是原子操作，避免了
helm repo update的网络抖动风险 - 多个 chart 共享同一 registry 凭据，权限模型比 HTTP basic auth 更清晰
- 但调试困难：没有
helm repo list对应的oras list，得靠 registry UI 或curl -H "Authorization: ..." https://reg/v2/_catalog查
OCI artifact 的核心约束就一条：media type 必须真实反映内容，且 registry 必须认它。推错一次，后续拉取链就断了，重试前先 oras delete 干净再推。
