🪞 镜像

Packagist 官方维护了一批地理镜像源，用于在无法稳定访问 packagist.org 的地区加速包元数据下载。本页说明镜像的概念、官方镜像列表，以及如何在 SDK 中切换到镜像。

源码位置

本页基于 pkg/repository/mirrors.go。该文件目前仅包含官方镜像的注释参考，未提供镜像常量或镜像列表方法——镜像切换通过 WithBaseURL / WithRepoURL 或 Options.ServerUrl 配置实现。

为什么需要镜像

• 🌐 地区网络：部分地区的开发者直连 packagist.org 延迟高、不稳定。
• ⚡ 加速：镜像与本地网络更近，拉取包元数据与索引更快。
• 🔄 可靠性：主站波动时镜像可作 fallback。
• 🏢 企业内部：自建 Packagist / Satis 实例作为私有 + 公开包的统一入口。

官方镜像

Packagist 官方推荐镜像列表见 https://packagist.org/mirrors。常见的社区镜像包括：

镜像	区域	备注
packagist.org	全球	官方主站
各地区社区镜像	视情况	见官方 mirrors 页面最新列表

镜像列表会变化

pkg/repository/mirrors.go 中明确标注「官方推荐的镜像源」参考自 https://packagist.org/mirrors，该列表会随时间变化。使用前请以官方页面为准，SDK 不内置镜像 URL 常量。

在 SDK 中切换镜像

ComposerClient 的所有读取方法都拼接 baseURL（业务 API）或 repoURL（V2 元数据），因此切换镜像只需覆盖这两个值。

方式一：高级门面（推荐）

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/scagogogo/composer-skills/pkg/client"
)

func main() {
    c := client.NewComposerClient(
        30*time.Second,
        // 业务 API 端点指向镜像
        client.WithBaseURL("https://packagist.mirror.example.com"),
        // V2 元数据端点指向镜像的 repo 子域
        client.WithRepoURL("https://repo.packagist.mirror.example.com"),
    )

    stats, err := c.GetStatistics()
    if err != nil {
        log.Fatalf("访问镜像失败: %v", err)
    }
    fmt.Printf("镜像包总数: %d\n", stats.Totals.Packages)
}

镜像 URL 结构

不同镜像的 URL 结构可能不同：有的镜像把 /packages/list.json、/statistics.json 等都放在同一域名下；有的则把 p2/... V2 元数据放在独立子域。配置前请查阅所选镜像的文档，分别填 WithBaseURL 与 WithRepoURL。

方式二：底层 Repository + 代理

如果镜像本身需要通过代理访问（如企业内网代理），或你想同时指定 server URL 与代理，用底层 Repository 层：

repo := repository.NewRepository(repository.Options{
    ServerUrl: "https://packagist.mirror.example.com",
    Proxy:     "http://127.0.0.1:7890",
})
stats, err := repo.Statistics(ctx)

详见 Options。

自建镜像 / Satis

如果你用 Satis 或私有 Packagist 实例作为内部镜像，配置方式相同——把 baseURL / ServerUrl 指向你的实例地址即可。SDK 的请求路径（/packages/list.json、/api/security-advisories/ 等）遵循 Packagist API 约定，只要你的实例兼容这些路径就能直接工作。

私有包的认证

自建实例若需认证，当前 ComposerClient 仅在三个写操作（Create/Edit/UpdatePackage）中携带 username / apiToken（作为 URL 查询参数）。读取方法不携带认证。如果你的私有镜像读取也需要认证，建议：

• 用底层 Repository + Proxy（在代理层加认证头），或
• 自行 fork 扩展 ComposerClient 增加 Authorization 头。

进阶

镜像同步延迟

镜像并非实时同步，通常有分钟级到小时级的延迟。因此：

• 🛠️ 刚发布的包可能在镜像上暂不可见——此时用 UpdatePackage 触发主站抓取，再等待镜像同步。
• 🔒 安全公告的镜像同步若有延迟，做漏洞告警时应以主站为准或确认镜像同步策略。

选镜像的取舍

维度	主站	镜像
实时性	最新	有延迟
速度	视地区	通常更快
数据完整性	权威	依赖镜像同步策略
公告	最及时	可能滞后

生产环境做安全监控时，建议公告走主站（GetSecurityAdvisories* 不覆盖 baseURL），大列表走镜像（ListPackages 等指向镜像加速）。

🔗 相关

• 🔌 客户端配置见 ComposerClient。
• ⚙️ 代理与 ServerUrl 见 Options。
• 🏗️ 底层 HTTP 见 Repository。