ProfileService

概览

字段	值
Kind	`Service` · 服务 Service
Realm	`common`

继承关系

Unit（4 属性 / 25 函数 / 6 事件）
- [ProfileService]（11 函数）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

ProfileService 提供分级日志、命名计时、客户端场景热力图读取，以及编辑器试玩态的 Lua CPU 火焰图和内存分配采集能力。

适用场景

需要输出诊断日志、测量一段脚本耗时、读取客户端渲染指标，或在编辑器试玩态定位 Lua CPU 与内存问题时使用。

使用要点

通过 game:GetService("ProfileService") 获取服务。Print/Warn/Error 用于日志；ProfileBegin/ProfileEnd 成对计时；GetSceneProfileData 在客户端读取热力图；编辑器试玩态下按 StartMemoryRecord、StartLuaProfile、StopLuaProfile、DumpLuaProfileStacks、StopMemoryRecord 的生命周期采集并导出分析文件。

注意事项

GetSceneProfileData 仅在客户端返回渲染数据，服务端返回空表。Lua 火焰图与内存记录接口仅编辑器试玩态可用，DumpLuaProfileStacks 写入当前进程工作目录；应检查各 Bool 返回值，并确保已开始的采集最终停止。不要把诊断输出或采样结果作为业务状态。

代码示例

在客户端读取场景性能数据并计时

lua

-- @runtime client
local profileService = game:GetService("ProfileService")

profileService:ProfileBegin("场景数据采样")
local sceneData = profileService:GetSceneProfileData()
local elapsedMs = profileService:ProfileEnd()

if type(sceneData) ~= "table" or next(sceneData) == nil then
    profileService:Warn("当前客户端尚未取得场景性能数据")
else
    profileService:Print(string.format("DrawCall=%s，采样耗时=%.2fms", tostring(sceneData.dp_num), elapsedMs))
end

关联类型

Unit

函数 (11)

Print

签名：Print(msg: Any) -> void

输出一条普通级别的日志消息。

参数	类型	说明
`msg`	`Any`	消息内容

返回值 void

示例代码

输出普通日志

lua

-- @runtime client
-- 获取 ProfileService 服务实例
local profileService = game:GetService("ProfileService")
-- 调用 Print 方法输出普通信息
profileService:Print("玩家进入游戏，ID: 12345")
-- 验证服务实例可用
print("ProfileService 实例获取成功:", profileService)

Warn

签名：Warn(msg: Any) -> void

输出一条警告级别的日志消息。

参数	类型	说明
`msg`	`Any`	消息内容

返回值 void

示例代码

输出警告日志

lua

-- @runtime client
-- 获取 ProfileService 服务实例
local profileService = game:GetService("ProfileService")
-- 调用 Warn 方法输出警告信息
profileService:Warn("内存使用率超过 80%，请注意性能")
-- 验证服务实例可用
print("ProfileService 实例获取成功:", profileService)

Error

签名：Error(msg: Any) -> void

输出一条错误级别的日志消息。

参数	类型	说明
`msg`	`Any`	消息内容

返回值 void

示例代码

输出错误日志

lua

-- @runtime client
-- 获取 ProfileService 服务实例
local profileService = game:GetService("ProfileService")
-- 调用 Error 方法输出错误信息
profileService:Error("发生了一个严重错误：网络连接超时")
-- 验证服务实例可用
print("ProfileService 实例获取成功:", profileService)

GetSceneProfileData

签名：GetSceneProfileData() -> Table (热力图数据 {model_prim_num, model_dp_num, prim_num, dp_num, fx_dp_num, logic_rate, render_rate, ts}；仅客户端有数据，服务端无渲染数据返回空表)

无参数调用。返回当前场景的热力图数据表，表中包含 model_prim_num、model_dp_num、prim_num、dp_num、fx_dp_num、logic_rate、render_rate、ts 等字段。该数据仅在客户端有内容，服务端没有渲染数据，因此调用返回空表。

返回值 Table (热力图数据 {model_prim_num, model_dp_num, prim_num, dp_num, fx_dp_num, logic_rate, render_rate, ts}；仅客户端有数据，服务端无渲染数据返回空表)

示例代码

示例：客户端读取场景热力图数据

lua

-- @runtime client
-- 获取 ProfileService：先取全局服务单例，后续调用都通过这个变量发起
local profileService = game:GetService("ProfileService")

-- 先输出一行日志，便于确认服务已就绪
profileService:Print("开始查看场景热力图")

-- ProfileBegin 开启一段命名计时，把要统计的代码包在中间
profileService:ProfileBegin("场景热力统计")
local sceneData = profileService:GetSceneProfileData()

-- ProfileEnd 结束最近一段计时并返回毫秒耗时，同时也能观察查询本身的开销
local elapsedMs = profileService:ProfileEnd()
print("计时耗时(ms):", elapsedMs)

-- 热力图数据仅在客户端可用，空表表示当前环境拿不到数据
if type(sceneData) == "table" and next(sceneData) ~= nil then
    print("模型Prim数:", sceneData.model_prim_num)
    print("DrawCall数:", sceneData.dp_num)
else
    print("当前环境无场景热力图数据")
end

ProfileBegin

签名：ProfileBegin(name: String) -> void

接收一个字符串参数 name，用于开始一段以该名称标识的代码计时。调用后可以用 ProfileEnd 结束最近一段计时并取得耗时。

参数	类型	说明
`name`	`String`	计时标签名

返回值 void

示例代码

示例：用 ProfileBegin 开启一段耗时统计

lua

-- @runtime client
-- 获取 ProfileService：先取全局服务单例，后续调用都通过这个变量发起
local profileService = game:GetService("ProfileService")

-- 先用 Print 打一条日志，方便和后面的计时结果对照
profileService:Print("开始查看场景热力图")

-- ProfileBegin 开启一段命名计时，把要统计的代码包在中间
profileService:ProfileBegin("场景热力统计")
local sceneData = profileService:GetSceneProfileData()

-- ProfileEnd 结束最近一段计时并返回毫秒耗时，同时也能观察查询本身的开销
local elapsedMs = profileService:ProfileEnd()
print("计时耗时(ms):", elapsedMs)

-- 场景热力图只在客户端有数据，空表表示当前环境拿不到数据
if type(sceneData) == "table" and next(sceneData) ~= nil then
    print("模型Prim数:", sceneData.model_prim_num)
    print("DrawCall数:", sceneData.dp_num)
else
    print("当前环境无场景热力图数据")
end

ProfileEnd

签名：ProfileEnd() -> Float (最近一段计时耗时（毫秒），无匹配开始段返回 0)

无参数调用。结束最近一段由 ProfileBegin 开启的计时，并返回该段计时耗时，单位为毫秒；若没有匹配的开始段，则返回 0。

返回值 Float (最近一段计时耗时（毫秒），无匹配开始段返回 0)

示例代码

示例：用 ProfileEnd 取得计时结果

lua

-- @runtime client
-- 获取 ProfileService：先取全局服务单例，后续调用都通过这个变量发起
local profileService = game:GetService("ProfileService")

-- 先输出一条日志，便于确认服务已就绪
profileService:Print("开始查看场景热力图")

-- ProfileBegin 开启命名计时，中间放置待统计的查询逻辑
profileService:ProfileBegin("场景热力统计")
local sceneData = profileService:GetSceneProfileData()

-- ProfileEnd 结束最近一段计时，返回值是耗时毫秒数；若没有匹配的开始段会返回 0
local elapsedMs = profileService:ProfileEnd()
print("计时耗时(ms):", elapsedMs)

-- 客户端下可以读到热力图字段；空表表示当前环境没有数据
if type(sceneData) == "table" and next(sceneData) ~= nil then
    print("模型Prim数:", sceneData.model_prim_num)
    print("DrawCall数:", sceneData.dp_num)
else
    print("当前环境无场景热力图数据")
end

StartLuaProfile

签名：StartLuaProfile() -> Bool (是否成功开始)

开始采集 Lua 性能数据，供后续生成火焰图使用，返回 Bool 表示是否成功开始。

返回值 Bool (是否成功开始)

示例代码

在编辑器试玩态采集 Lua CPU 数据

lua

-- @runtime client
local profileService = game:GetService("ProfileService")
local started = profileService:StartLuaProfile()
if started then
    -- 在这里执行需要分析的业务逻辑
    local stopped = profileService:StopLuaProfile()
    print("Lua CPU 采集是否成功结束:", stopped)
else
    print("当前环境未开始 Lua CPU 采集")
end

StopLuaProfile

签名：StopLuaProfile() -> Bool (是否成功结束)

结束 Lua 性能数据采集，返回 Bool 表示是否成功结束。

返回值 Bool (是否成功结束)

示例代码

结束已开始的 Lua CPU 采集

lua

-- @runtime client
local profileService = game:GetService("ProfileService")
if profileService:StartLuaProfile() then
    -- 在这里执行需要分析的业务逻辑
    local stopped = profileService:StopLuaProfile()
    print("Lua CPU 采集是否成功结束:", stopped)
end

DumpLuaProfileStacks

签名：DumpLuaProfileStacks(filePath: String) -> Bool (是否成功导出)

把已采集的 Lua 性能数据导出为火焰图 HTML 文件。参数 filePath 指定导出目标路径，返回 Bool 表示是否导出成功。

参数	类型	说明
`filePath`	`String`	如 "lua_dump.html"

返回值 Bool (是否成功导出)

示例代码

导出 Lua 火焰图 HTML

lua

-- @runtime client
local profileService = game:GetService("ProfileService")
local exported = profileService:DumpLuaProfileStacks("lua_dump.html")
print("Lua 火焰图是否成功导出:", exported)

StartMemoryRecord

签名：StartMemoryRecord() -> Bool (是否成功开始)

开始记录 Lua 内存分配，返回 Bool 表示是否成功开始。

返回值 Bool (是否成功开始)

示例代码

记录一段 Lua 内存分配

lua

-- @runtime client
local profileService = game:GetService("ProfileService")
local started = profileService:StartMemoryRecord()
if started then
    -- 在这里执行需要分析的业务逻辑
    local stopped = profileService:StopMemoryRecord()
    print("内存记录是否成功停止:", stopped)
end

StopMemoryRecord

签名：StopMemoryRecord() -> Bool (是否成功停止)

停止记录 Lua 内存分配，返回 Bool 表示是否成功停止。

返回值 Bool (是否成功停止)

示例代码

停止已开始的 Lua 内存记录

lua

-- @runtime client
local profileService = game:GetService("ProfileService")
if profileService:StartMemoryRecord() then
    -- 在这里执行需要分析的业务逻辑
    local stopped = profileService:StopMemoryRecord()
    print("内存记录是否成功停止:", stopped)
end

技能资源包

基础教程

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

数据

枚举

服务

单位

枚举 Enum

数据 Data

服务 Service

单位 Unit

ProfileService

概览

继承关系

适用场景

使用要点

注意事项

代码示例

在客户端读取场景性能数据并计时

关联类型

函数 (11)

Print

Warn

Error

GetSceneProfileData

ProfileBegin

ProfileEnd

StartLuaProfile

StopLuaProfile

DumpLuaProfileStacks

StartMemoryRecord

StopMemoryRecord

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

ProfileService ​

概览 ​

继承关系 ​

适用场景 ​

使用要点 ​

注意事项 ​

代码示例 ​

在客户端读取场景性能数据并计时 ​

关联类型 ​

函数 (11) ​

Print ​

Warn ​

Error ​

GetSceneProfileData ​

ProfileBegin ​

ProfileEnd ​

StartLuaProfile ​

StopLuaProfile ​

DumpLuaProfileStacks ​

StartMemoryRecord ​

StopMemoryRecord ​

ProfileService

概览

继承关系

适用场景

使用要点

注意事项

代码示例

在客户端读取场景性能数据并计时

关联类型

函数 (11)

Print

Warn

Error

GetSceneProfileData

ProfileBegin

ProfileEnd

StartLuaProfile

StopLuaProfile

DumpLuaProfileStacks

StartMemoryRecord

StopMemoryRecord