需在 composer.json 中配置私有 Packeton 源并禁用 packagist.org：设置 "repositories" 为 Packeton 地址，添加 "packagist.org": false；同时在 auth.json 中配置 Bearer Token 认证，并确保 Webhook 正确触发同步。
怎么让 Composer 读取 Packeton 私有源
默认情况下，Composer 不会自动信任或拉取 Packeton 源，必须显式配置 repositories 并禁用 Packagist 公共索引。否则 composer install 仍会回退到 packagist.org，甚至报 Package not found 错误。
- 在项目根目录的
composer.json中，用repositories替换默认源："repositories": [ { "type": "composer", "url": "https://your-packeton.example.com" } ] - 务必加上
"packagist.org": false，否则 Packeton 里没有的包仍会去公网查（可能暴露内部依赖结构）："repositories": { "packagist.org": false, "packeton": { "type": "composer", "url": "https://your-packeton.example.com" } } - Packeton 实例需开启
allow-packages-from-packagist（如果想混用部分公共包），但该选项默认关闭；开启后仍建议在composer.json中显式声明哪些包允许走公网，避免意外泄漏
为什么 composer require 找不到私有包
常见现象是执行 composer require vendor/private-package 报错 Could not find package vendor/private-package，本质不是网络问题，而是 Packeton 没把包“暴露”给 Composer 的元数据接口。
- 确认该包已在 Packeton 后台被“启用”（Enabled）：Packeton 默认导入包后处于
disabled状态，需手动点击开关或调用 API 启用 - 检查包名是否完全匹配：Packeton 对大小写敏感，
vendor/MyPackage和vendor/mypackage被视为不同包 - Packeton 的
require行为依赖packages.json缓存，首次添加包后需触发一次php bin/console packeton:update --force，否则 Composer 请求时返回空列表 - 如果使用了团队权限隔离（Team Scopes），当前用户 Token 必须属于能访问该包的 Team，否则即使包已启用，API 返回仍是 404
Token 认证失败：401 或 403 怎么调
Packeton 要求所有私有源请求带 Authorization: Bearer ，但 Composer 自身不支持对每个源单独设 token —— 必须靠 auth.json 绑定域名。
- 在项目目录或全局
COMPOSER_HOME下创建auth.json，内容为：{ "http-basic": { "your-packeton.example.com": { "username": "token", "password": "your-api-token-here" } } } - Token 必须是 Packeton 后台生成的 User API Token（
Settings → API Tokens），不是登录密码，也不是 OAuth token - 如果用 Nginx 反代 Packeton，确认反代配置透传了
Authorization头；常见漏掉proxy_pass_request_headers on;导致 401 - Packeton 日志路径通常是
var/log/prod.log，搜索Invalid credentials可快速定位是 token 过期、权限不足还是域名不匹配
Packeton 同步失败：为什么有些包始终不更新
Packeton 的同步不是实时的，尤其当源是 GitHub/GitLab 时，常出现“代码已推、但 Composer 还拉不到新版本”，根本原因是 Packeton 依赖 Webhook 触发更新，而非轮询。
- GitHub 侧必须在仓库
Settings → Webhooks添加地址为https://your-packeton.example.com/webhook/github的推送（Payload URL），Content type 选application/json，事件勾选Releases和Pushes - GitLab 需开启
Tag push events和Push events，Webhook URL 是https://your-packeton.example.com/webhook/gitlab - 若没配 Webhook，只能手动执行
php bin/console packeton:sync vendor/package-name，但无法自动感知新 tag - 注意：Packeton 默认只同步带语义化版本 tag（如
v1.2.3）的发布，dev-main或test-branch这类非标准 tag 不会被收录，除非在后台包设置中开启Allow unstable versions
Packeton 的“私有源”逻辑比表面复杂：它既是代理，也是缓存+权限网关。很多问题其实卡在认证链路或 webhook 配置这种边缘环节，而不是 Composer 命令本身。调试时优先看 auth.json 域名是否和 repositories.url 完全一致，再查 Packeton 日志里的 HTTP 状态码，比反复改 composer.json 有效得多。
