cocos creator -show fps无效？如何正确启用帧率显示？

Question

在使用 Cocos Creator 开发游戏时，部分开发者尝试通过命令行启动参数 `-show-fps` 来启用帧率显示，但发现该参数无效，界面上并未出现 FPS 信息。此问题通常出现在 Cocos Creator 3.x 版本中，原因是引擎已弃用该命令行参数，转而采用更灵活的 `DebugHelper` 组件或代码方式实现。正确启用 FPS 显示的方法是在场景中动态添加 `cc.debug.setDisplayStats(true)` 或通过代码 `director.setStats(true)` 启用性能统计。此外，需确保项目构建或运行环境支持调试面板，且未在发布版本中禁用相关功能。理解新旧版本差异并采用推荐 API 是解决 `-show-fps` 无效的关键。

Answer 1

1. 问题背景与现象描述

在使用 Cocos Creator 开发游戏时，部分开发者尝试通过命令行启动参数 -show-fps 来启用帧率显示，但发现该参数无效，界面上并未出现 FPS 信息。这一现象在 Cocos Creator 3.x 版本中尤为常见。

早期版本（如 Cocos Creator 2.x）中，-show-fps 是一个有效的调试参数，能够直接在运行时显示帧率、内存占用等性能指标。然而，随着引擎架构的演进，该命令行参数在 3.x 版本中已被弃用。

2. 技术演进与设计变更

Cocos Creator 3.x 引入了更现代化的渲染架构和模块化设计，原有的基于全局宏或启动参数的调试方式不再适用。引擎团队将性能统计功能迁移至更灵活的 API 控制体系中，推荐使用代码方式动态控制调试面板的显示。

主要变更包括：

• 移除对 -show-fps 命令行参数的支持
• 引入 DebugHelper 组件用于可视化调试信息
• 提供 cc.debug.setDisplayStats(true) 和 director.setStats(true) 等运行时 API
• 支持按需开启/关闭性能面板，提升调试灵活性

3. 正确启用 FPS 显示的方法

在 Cocos Creator 3.x 中，启用 FPS 显示应采用以下任一方法：

1. 通过脚本代码启用：在场景加载时调用如下代码：

import { director } from 'cc';
// 启用性能统计
director.setStats(true);

1. 使用调试辅助类：调用全局调试接口：

import { debug } from 'cc';
debug.setDisplayStats(true);

1. 添加 DebugHelper 组件：在 Canvas 节点上添加 DebugHelper 组件，可在编辑器中直接配置显示项。

4. 环境与构建配置影响分析

FPS 面板是否可见还受构建配置影响。以下是关键检查点：

配置项	开发环境	发布版本	说明
Enable Debug Stats	✅ 默认开启	❌ 可能被禁用	需手动确保未被移除
Build with Source Maps	✅ 推荐开启	❌ 通常关闭	影响调试能力
Define Constants: DEBUG	✅ 为 true	❌ 编译时移除	决定是否包含调试代码

5. 诊断流程图：排查 FPS 不显示问题

graph TD
            A[启动游戏无FPS显示] --> B{是否使用 -show-fps 参数?}
            B -- 是 --> C[该参数已废弃, 不再生效]
            B -- 否 --> D[检查是否调用 setStats(true)]
            D --> E{是否成功启用?}
            E -- 否 --> F[确认代码执行时机是否正确]
            E -- 是 --> G{构建版本是否剥离调试模块?}
            G -- 是 --> H[修改构建配置保留调试信息]
            G -- 否 --> I[FPS 应正常显示]
            F --> J[建议在 Scene Load 回调中调用]

6. 实际项目中的最佳实践

对于有 5 年以上经验的开发者，在实际项目中应遵循以下最佳实践：

• 避免依赖已被弃用的命令行参数，关注官方文档更新
• 封装统一的调试管理模块，例如 DebugManager.ts
• 根据构建模式自动控制调试面板的开启状态
• 结合远程调试工具（如 Chrome DevTools）进行深度性能分析
• 利用 Profiler 模块进行帧耗时、GC 频率等高级监控
• 在 CI/CD 流程中加入自动化性能检测脚本

7. 兼容性处理与版本迁移策略

当从 Cocos Creator 2.x 迁移到 3.x 时，需注意以下兼容性问题：

// 旧版本写法（已失效）
// cc.game.showStats();

// 新版本写法
import { director } from 'cc';
director.setStats(true);

建议在迁移过程中建立“适配层”，封装版本差异：

class PerformanceMonitor {
    static enable() {
        if (CC_DEBUG) {
            // 兼容不同版本
            if (director.setStats) {
                director.setStats(true);
            } else if ((cc as any).debug?.setDisplayStats) {
                (cc as any).debug.setDisplayStats(true);
            }
        }
    }
}