TracyClient.cpp必须编译进主项目而非仅链接静态库，因Profiler单例依赖全局构造器初始化，未引用的.o文件易被链接器丢弃；需显式加入构建系统、禁用/GL、定义TRACY_ENABLE、适配PIE及符号路径对齐。
TracyClient.cpp 必须编译进主项目，不能只链接静态库
很多开发者以为把 libtracy.a 链进去就完事了，结果运行时 TracyStartup 不生效、ZoneScoped 完全没数据——根本原因是 Tracy 的 Profiler 单例（tracy::Profiler）依赖全局构造器触发初始化，而静态库中未被引用的.o文件可能被链接器丢弃。
实操建议：
立即学习“C++免费学习笔记（深入）”；
-
TracyClient.cpp和Tracy.hpp必须显式加入你的构建系统：CMake 用户用target_sources(your_target PRIVATE TracyClient.cpp)，不要只靠target_link_libraries - MSVC 下禁用
/GL（全程序优化），否则__declspec(dllexport)在静态库中失效，导致tracy::GetProfiler()返回空指针 - Linux/macOS 若主程序启用了
-pie（如 Android NDK 默认），需定义TRACY_NO_FRAME_IMAGE，否则TracyAlloc内存映射失败，客户端静默退出
TRACY_ENABLE 宏必须在所有构建模式下显式定义
Release 模式下 ZoneScoped 等宏默认为空——不是 Tracy “变慢了”，是它被预处理器直接删掉了。现象是：Debug 下能看到完整时间线，Release 下 tracy-server 显示 “No connection” 或连接后几秒断开。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- CMake 中统一加：
add_compile_definitions(TRACY_ENABLE)，不要只在 Debug 中加 - 确保该宏在
Tracy.hpp被 include 前已定义；若用 PCH，把它塞进预编译头最顶部 - Android NDK 构建时，在
Application.mk或CMakeLists.txt的cppFlags里加-DTRACY_ENABLE，别依赖 build type 自动推导
ZoneScoped 在循环/协程/异步回调中会失效
ZoneScoped 本质是 RAII，依赖栈帧连续性。一旦遇到内联优化、尾调用、协程挂起、跨线程回调，它的作用域就“断开”，GUI 中显示为 “Unknown Zone” 或时间线错位。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 循环体内改用
TracyZoneN("loop body")+ 手动TracyZoneEnd()，避免每轮析构开销和栈断裂 - C++20 协程或 std::async 回调中，必须用 C 风格句柄：
TracyCZone ctx = TracyCZoneN("async task")，并在回调结束前调用TracyCZoneEnd(ctx) - 函数内测某段 malloc 耗时？别写
ZoneScoped，改用TracyZoneS("malloc")+TracyZoneEnd()，确保标记与实际执行严格对齐
Android GPU 时间归零、VS Code 跳转失败、Unity WebGL 报错的共性原因
这三个看似无关的问题，根因都是符号路径未对齐：Tracy GUI 需要绝对路径匹配源码位置才能跳转、解析帧图像、关联 GPU 时间戳。Android NDK 编译产物路径含随机 hash，Unity IL2CPP 输出的符号表被 strip，VS Code 的 sourceFileMap 未重映射构建目录。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- Android：在
build.gradle的externalNativeBuild中加arguments "-fdebug-prefix-map=${projectDir}/src/main/cpp=."，让调试路径归一化 - VS Code：在
.vscode/c_cpp_properties.json的sourceFileMap里补全构建路径映射，例如"${workspaceFolder}/build/src": "${workspaceFolder}/src" - Unity：关闭 IL2CPP 的 “Strip Engine Code”，并确保 Player Settings → Other Settings → Scripting Backend 设为 IL2CPP 且勾选 “Development Build”
跨平台真正难的不是编译，是让每个平台上的路径、符号、内存模型都对得上 Tracy 的遥测协议。连不上、看不到、跳不进——八成是路径或符号链断了一环，而不是工具本身有问题。
