使用说明
uniprof
uniprof为人类和AI代理简化了CPU性能分析。无需修改代码或添加额外依赖，即可对任何应用程序进行性能分析。
# Profile and analyze any app in one step
npx uniprof python script.py
目录
支持的平台
uniprof 在多个专门针对不同平台和运行时的性能分析器之上实现了一个通用接口。它能够根据正在执行的命令自动检测应使用哪个性能分析器，运行该分析器，将不同输出格式转换为统一格式，并对数据进行统计分析以识别热点。
| 平台 | 分析器 | 容器 | 主机 | 最低版本 |
|---|---|---|---|---|
| python py-spy | ✅ | ✅ | Python 3.7+ | （翻译为） |
| Node.js | 0x | ✅ | ✅ | Node 14+（节点14及以上版本） |
| 红宝石 | rbspy（注：这个词汇在中文中并没有直接对应的翻译，因为它可能是一个特定领域或上下文中的专有名词或缩写。如果它是一个程序、工具或特定概念的名称，那么翻译时可能需要根据其具体含义来确定。在这里，我们直接保留原词，因为它可能是一个特定的术语或缩写，没有通用的中文翻译。） | ✅ | ✅ | Ruby 2.5及以上版本 |
| PHP | 准分子 | ✅ | ✅ | PHP 7.2+（或：PHP 7.2及以上版本） |
| JVM | （Java虚拟机） `async-profiler` 翻译为中文是“异步分析器”或“异步性能分析工具” | ✅ | ✅ | Java 8+ |
| 。NET | dotnet-trace | ✅ | ✅ | .NET 5+ |
| BEAM | （注：BEAM在此处可能是一个特定术语、项目名或缩写，根据上下文可能有不同的翻译，但直接翻译为“光束”或保持原样作为专有名词也是可行的。） perf（此处为英文原词，中文无直接对应词汇，若作为缩写或特定语境下的用词，可能需具体情境来翻译，但一般可理解为“性能”或“表现”等概念的简写，不过直接翻译仍为“perf”） | ✅ | ✅* | 一次性密码（OTP）24小时以上 |
| 原生（macOS） | 乐器；工具 | ❌ | ✅ | Xcode 14.3+ |
| 原生（Linux） | perf（此处为英文单词，直接翻译为中文可保持原样，若需意译，根据上下文可理解为“完美”或“出色”等，但在此处作为独立词汇，直接使用“perf”即可） | ✅ | ✅ | Linux 2.6.31+ |
* Linux仅用于主机模式
系统要求
太长，读不下去了 安装了Docker的macOS或Linux系统
uniprof 设计为可在 macOS 和 Linux 上运行，但主要是在 macOS 上进行开发和测试的。如果您在 Linux 上运行时发现任何错误，请 报告他们目前不支持在Windows主机上运行，但您可以在Windows上安装的Linux系统中运行 WSL2（Windows Subsystem for Linux 2）请注意，当通过WSL2使用Uniprof时，不支持对原生Windows可执行文件进行性能分析，但您仍然可以使用分析器来分析像Python和Node.js这样的高级语言运行时。
性能分析工具往往不容易正确设置，并且可能需要 提升权限为了简化设置并为配置文件代码提供更好的隔离，uniprof 默认使用 Docker 容器 对于每个已预配置为运行特定分析工具的运行时，uniprof会在容器中挂载您的工作区，并在附加分析器的情况下执行程序。此外，如果主机系统已安装分析工具，uniprof还支持在容器外部进行分析，方法是通过运行（使用相应的命令或参数） --mode host 标志。唯一不支持容器化执行的情况是，在 macOS 上对原生 Mach-O 二进制文件进行性能分析时，因为 Apple Instruments 无法在容器内运行。
安装
npm install -g uniprof
MCP服务器
# Install uniprof MCP server automatically
uniprof mcp install claudecode
uniprof mcp install cursor
uniprof mcp install vscode
支持自动安装的客户端： amp、claudecode、codex、cursor、gemini、vscode、zed
如果您的客户端不支持自动安装，请使用命令通过stdio传输方式添加一个MCP服务器 npx -y uniprof mcp run。
如需详细的MCP文档，请参阅 docs/mcp.md 翻译为中文是：文档/mcp.md（或“说明文件/mcp.md”，具体翻译可能根据上下文有所调整，但“文档”是最常见的翻译）。
快速入门
一步完成配置文件和分析：
# Profile most languages and get immediate analysis
uniprof python app.py
uniprof node server.js
uniprof ruby script.rb
uniprof java -jar myapp.jar
uniprof dotnet MyApp.dll
uniprof ./my-native-app
# Profile and visualize flamegraph in browser
uniprof --visualize python app.py
保存配置文件以便后续分析和可视化:
# 1. Check environment (optional)
uniprof bootstrap
# 2. Record a profile
uniprof record -o profile.json -- python app.py
uniprof record -o profile.json -- node server.js
uniprof record -o profile.json -- ruby script.rb
uniprof record -o profile.json -- php script.php
uniprof record -o profile.json -- java -jar myapp.jar
uniprof record -o profile.json -- ./gradlew run
uniprof record -o profile.json -- ./mvnw spring-boot:run
uniprof record -o profile.json -- dotnet MyApp.dll
uniprof record -o profile.json -- elixir script.exs
uniprof record -o profile.json -- mix run
uniprof record -o profile.json -- ./my-native-app
uniprof record -o profile.json -- /Applications/MyApp.app
# 3. Analyze profile data to find hotspots
uniprof analyze profile.json
# 4. Visualize flamegraph in the browser
uniprof visualize profile.json
有关详细命令行选项的文档，请参阅 docs/cli.md 翻译为中文是：“文档/命令行界面.md” 或者更简洁地表述为“文档/CLI指南.md”，其中“CLI”代表“Command Line Interface”（命令行界面）。
主机模式与容器模式
使用 --mode 控制性能分析运行方式的选项：
- **
auto（默认）**当Docker可用时，优先使用容器模式；否则使用主机模式。- 语言运行时（Python/Node.js/Ruby/PHP/BEAM/JVM/.NET）默认使用容器以实现零配置。
- 在macOS上，使用Mach-O二进制文件的本地应用会使用主机（Instruments）。macOS上的ELF二进制文件支持在容器模式下运行。
- 在Linux上，Native默认使用容器；如果您更倾向于使用本地性能设置，可以选择使用主机。
- **
host**强制使用主机安装的性能分析器。 - **
container**强制使用 Docker 容器（不支持 macOS Instruments/Mach-O 二进制文件）。
# Auto mode (default)
uniprof record -o profile.json -- python script.py
# Force host profilers
uniprof record --mode host -o profile.json -- python script.py
# Force container mode
uniprof record --mode container -o profile.json -- ./my-linux-app
编译时包含调试信息
原生性能分析需要调试信息才能得出有意义的结果。调试符号使性能分析工具能够将内存地址映射到函数名，从而提供可读的输出，而不仅仅是十六进制地址。此外，帧指针提高了调用栈的准确性，尤其是在处理优化代码时。
| 编译器 | DWARF 调试信息 | 帧指针 | 备注 |
|---|---|---|---|
| 项目 | 英文名称 | 中文名称 | 数量 |
| 用于GDB特定的扩展 | ** | ** clang（在编程或编译上下文中，可译为“编译器报错声”或简化为“编译报错”） clang -g -o myapp main.cpp |
clang -fno-omit-frame-pointer -o myapp main.cpp |
| 在 macOS 上获取完整的调试信息 | ** | ** Swift（编程语言） swiftc -g main.swift |
swiftc -Xcc -fno-omit-frame-pointer main.swift |
| ** | ** 货物 cargo build |
cargo build --release （调试模式） [profile.release]debug = true + RUSTFLAGS="-C force-frame-pointers=yes" cargo build |
debug = true 调试构建默认包含DWARF；对于发布构建，请添加 |
| 到 Cargo.toml | ** | ** 走 go build -gcflags=all="-N -l" |
-gcflags |
| 禁用优化以提高调试效果 | ** | ** zig（吉格，一种舞蹈风格或品牌名，具体含义需根据上下文确定） zig build-exe -O Debug main.zig |
zig build-exe -fno-omit-frame-pointer main.zig |
| 带有符号的优化构建的调试信息 | ** | ** ghc ghc -g -rtsopts main.hs |
ghc -fno-omit-frame-pointer main.hs |
启用运行时性能分析选项 |
MCP 服务器
- 功劳；学分；积分 py-spy (MIT) 用于 Python 性能分析。包含在 uniprof-python（可译为“UniProf的Python项目”或根据具体上下文简化为“UniProf Python”）
- 图像。 0x (MIT) 用于 Node.js 的性能分析。包含在 uniprof-nodejs（可译为“UniProf Node.js”，但具体翻译可能需根据上下文调整，若“uniprof”为特定项目或组织名，则保留原样）
- 图片。 rbspy（该词可能是一个特定软件或工具的名称，直接翻译为中文无具体含义，若作为专有名词保留原样） (MIT) 用于 Ruby 性能分析。包含在 uniprof-ruby（可译为“UniProf-Ruby”，但具体翻译可能需根据上下文调整，若“uniprof”为特定项目或品牌名，则保持原样）
- 图像。 准分子 (Apache 2.0) 用于 PHP 性能分析。包含在 uniprof-php（可译为“UniProf PHP”或根据具体上下文可能意为“统一专业PHP”等，但通常直接保留原样以指代特定项目或框架）
- 图像。 async-profiler（异步分析器） (Apache 2.0) 用于 JVM 性能分析。已包含在 uniprof-jvm（注：此词可能是一个特定项目、组织或技术的名称，直接翻译为中文可能无具体含义，故保持原样。若需根据上下文翻译，需提供更多背景信息。）
- 图像。 dotnet-trace（可译为“.NET 跟踪”或根据具体语境译为“.NET 追踪工具”） (MIT) 用于 .NET 性能分析。包含在 uniprof-dotnet（可译为“UniProf .NET”或保持原样，具体取决于上下文和是否需要意译）
- 图片。 perf（在计算机领域，通常指“性能”或“性能分析”的缩写） (GPL) 用于在 Linux 上进行本机性能分析。包含在 uniprof-native 可以翻译为“原生多语言支持”或“原生多语种功能”，具体取决于上下文语境。在这里，我选择了“原生多语言支持”作为翻译，因为它较为通用且易于理解 并且 uniprof-beam（可译为“专业光束”或根据具体上下文调整，但直接翻译保持原样为“uniprof-beam”）
- 图片。 Speedscope（注：此处为专有名词，直接音译，若“Speedscope”有特定含义或品牌名，则应根据具体语境翻译）
(MIT) 与 uniprof 一起打包，用于火焰图可视化
许可证 **此仓库中的所有uniprof源代码均受以下许可协议约束：**麻省理工学院许可证 LICENSE. 查看
. UniProf下载并运行 Docker 镜像 containers/那个包含第三方软件的包。用于构建这些镜像的Dockerfile可以在
