需升级PHP至8.0+并安装gmp、apcu扩展；若无法启用apcu，应改用RedisStorage等共享后端；务必正确引入autoload.php、注册采集器、复用Registry单例，并避免在Swoole中使用APCuStorage。
composer require promphp/prometheus-client 失败怎么办
直接运行 composer require promphp/prometheus-client 大概率报错，常见原因是 PHP 版本或扩展不满足最低要求。这个包要求 PHP ≥ 8.0，且默认启用 ext-gmp（用于高精度计数器哈希）和 ext-apcu（用于内存存储后端）。如果你用的是 PHP 7.4 或没装 APCu，composer install 会中断并提示 “class APCuAdapter not found” 或 “gmp_init(): GMP extension is required”。
- 先确认 PHP 版本：
php -v，低于 8.0 就别硬试，得升级或换方案 - 检查扩展是否加载：
php -m | grep -E 'gmp|apcu'，缺哪个就装哪个（如 Ubuntu：sudo apt install php-gmp php-apcu） - 如果实在不能装 APCu，可以强制禁用它，在
require后手动指定存储后端，比如用NullStorage（仅测试用）或RedisStorage（需额外配 Redis）
为什么 new Prometheus\CollectorRegistry() 报 Class not found
不是类名写错，而是自动加载没触发——Composer 没生成 autoload 文件，或你没 require 'vendor/autoload.php'。这个错误几乎只出现在“手动复制代码但忘了引入 Composer 自动加载”的场景。
- 确保项目根目录有
vendor/autoload.php（即已成功执行过composer install或composer require） - 脚本开头必须有：
require __DIR__ . '/vendor/autoload.php';，路径要对，别写成./vendor/autoload.php在 CLI 下可能出问题 - 如果用在 Laravel 或 Symfony 等框架里，通常不用手动 require，但得确认框架的 autoloader 已加载该包命名空间（
Prometheus\*）
暴露 /metrics 接口时 Counter::inc() 不生效
指标注册了、inc() 也调用了，但访问 /metrics 返回空或只有默认指标，核心原因通常是：采集器没被 Registry 收录，或 Exporter 没从 Registry 拿最新状态。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 必须显式将 Collector 加入 Registry：
$registry->registerCollector($counter)，不能只 new 出来就完事 - Exporter 输出前要确保 Registry 是“当前最新”：
(new TextFormat())->render($registry->getMetricFamilySamples())，别传错对象（比如传了旧的 $registry 实例） - Web 路由中每次请求都 new Registry 是错的——会导致指标重置；应该单例复用（如存在全局变量、容器绑定或静态属性）
- 如果用了 APCu 存储，注意 APCu 的 shared memory 是进程级的，PHP-FPM 下多个 worker 可能看不到彼此的计数，得切到 Redis 或其他共享后端
在 Swoole 或 Hyperf 中使用 promphp/client 报错
Swoole 默认不支持 APCu 的 fork-safe 行为，而 promphp/client 的 APCuStorage 在子进程里会丢失数据甚至崩溃，典型错误是 APCu is not available in this process 或 segfault。
立即学习“PHP免费学习笔记（深入）”；
- 禁止在 Swoole 主进程/Worker 中使用
APCuStorage，改用RedisStorage或MemoryStorage（仅限单 Worker 测试） - Hyperf 用户可直接用
hyperf/metric组件，它已内置适配，比直接套 promphp/client 更稳 - 若坚持用原生 client，初始化 Registry 时必须传入非 APCu 的 Storage：
new CollectorRegistry(new RedisStorage($redis)) - 注意 Swoole 的协程上下文：
Counter实例不能跨协程共享（除非加锁），建议按请求/协程隔离创建，或用标签（label）区分维度
真正难的不是装上，而是让指标在长生命周期、多进程、协程环境下持续准确——APCu 看似省事，恰恰是线上最常翻车的一环。
