SmartBugs 跨平台安装终极指南：Windows/macOS/Linux 避坑全攻略

【免费下载链接】smartbugsSmartBugs: A Framework to Analyze Ethereum Smart Contracts项目地址: https://gitcode.com/gh_mirrors/smar/smartbugs

SmartBugs 是一个用于分析以太坊智能合约安全漏洞的开源框架，号称"一套命令跑遍 25 款安全分析工具"。但很多新手在跨平台安装 SmartBugs 时，往往卡在 Docker 权限、Python 版本、虚拟环境等环节。本文为你整理了一份SmartBugs 跨平台安装避坑全攻略，覆盖 Windows、macOS、Linux 三大系统的完整步骤与常见坑点，照着做 10 分钟即可跑通。

一、SmartBugs 是什么？为什么值得装？

简单说，SmartBugs 把 Mythril、Slither、Oyente+、Semgrep、Solhint 等 25 款智能合约分析工具封装成了统一的命令行入口，支持分析 Solidity 源码、部署字节码和运行时代码三种模式，还能自动下载匹配的 solc 编译器版本，并把结果统一解析成标准格式甚至 SARIF 报告。

对新手来说，最大的价值是不用逐个安装配置这些工具，SmartBugs 通过 Docker 镜像隔离了每种工具的依赖环境。这也是它跨平台安装的核心逻辑：只要装好 Docker，剩下的事情框架都替你搞定。

二、安装前必读：环境要求清单

在动手前，先对照这份清单自查，能避开 80% 的坑：

官方完整说明见 doc/installation.md，依赖清单见 pyproject.toml。

三、第一步：安装 Docker（三大平台通用前提）

Docker 是 SmartBugs 的"心脏"，请务必确保：

• Linux：安装 Docker Engine 后，需要把当前用户加入docker组，否则每次都要sudo且会报权限错误：

sudo usermod -a -G docker $USER

⚠️ 加入 docker 组后必须重新登录（或注销再登录）才生效，这是 Linux 上最常见的"装完报权限"原因。

• macOS / Windows：安装 Docker Desktop 并保持运行即可。首次启动会要求授权，注意macOS 的 Docker Desktop 需要系统设置里给予权限；Windows 建议开启 WSL2 后端（见下文 Windows 章节）。

四、Linux 安装 SmartBugs 完整步骤

Linux 是 SmartBugs 的"原生主场"，流程最顺畅，推荐新手优先用 Linux 或云服务器体验。

1. 克隆仓库

git clone https://gitcode.com/gh_mirrors/smar/smartbugs cd smartbugs

2. 一键安装依赖

仓库自带了一键虚拟环境脚本，会自动创建.venv、升级 pip、安装 Poetry 并拉取所有 Python 依赖：

install/setup-venv.sh

💡 脚本源码可查看 install/setup-venv.sh。如需开发测试环境（pytest 等），加--dev参数：install/setup-venv.sh --dev。

3. 验证安装

./smartbugs --version

能打印版本号即安装成功。

4.（可选）加入 PATH 全局调用

想把smartbugs、reparse、results2csv变成全局命令，可以创建软链接：

ln -s "`pwd`/smartbugs" "$HOME/bin/smartbugs" ln -s "`pwd`/reparse" "$HOME/bin/reparse" ln -s "`pwd`/results2csv" "$HOME/bin/results2csv"

之后执行which smartbugs能看到路径就说明配置成功。

五、macOS 安装 SmartBugs：两大避坑点

macOS 的安装步骤与 Linux 基本一致（无需 usermod 操作），但有两大专属坑：

坑 1：Apple Silicon（M1/M2/M3）芯片兼容性

Docker Desktop 在 Apple 芯片上默认运行 arm64 架构，个别老工具镜像可能没有 arm64 版本。遇到拉取失败时，可在 Docker Desktop 设置中开启"Use Rosetta for x86_64/amd64 emulation"，或给镜像加--platform linux/amd64参数。

坑 2：Python 版本管理

macOS 自带 Python 通常版本较老，务必先确认：

python3 --version

版本低于 3.10 时，建议用 Homebrew 安装新版：brew install python@3.12，然后重新执行安装脚本即可。

其余步骤与 Linux 完全相同：克隆 →install/setup-venv.sh→ 验证。

六、Windows 安装 SmartBugs 最稳方案：WSL2

Windows 上没有原生的一键安装脚本，官方推荐的方式也是借助 Linux 环境。最稳的组合拳是：WSL2 + Docker Desktop，相当于在 Windows 里跑一个轻量 Linux，然后走 Linux 安装流程。

操作路线图：

1. 安装WSL2：管理员 PowerShell 执行wsl --install，重启后安装一个 Ubuntu 发行版
2. 安装Docker Desktop：设置中勾选"Use the WSL 2 based engine"，并在 Resources → WSL Integration 中启用你的 Ubuntu
3. 进入 Ubuntu 终端，完全按照上文 Linux 章节操作：克隆仓库 → 运行install/setup-venv.sh→ 验证

🚨 三个高频坑：一是忘记启用 WSL Integration 导致 Ubuntu 里连不上 Docker；二是 PowerShell 与 WSL 的文件路径混乱，建议所有操作都在 Ubuntu 终端内完成；三是记得在 Ubuntu 里执行sudo usermod -a -G docker $USER并重新登录。

七、避坑总表：5 个最高频报错速查

如果分析中途中断，无需重新来过——SmartBugs 支持断点续跑，用相同参数再次执行即可恢复，这是它比裸用各工具省心的地方。

八、安装完成后：3 条命令快速上手

装好之后，先用项目自带的示例合约体验一下（示例见 samples/ 目录）：

# 用 mythril 分析所有示例合约，2 进程并行、内存上限 4G、单任务超时 600 秒 ./smartbugs -t mythril -f 'samples:**/*' --processes 2 --mem-limit 4g --timeout 600 # 解析结果（未加 --json/--sarif 时需手动解析） ./reparse results # 生成 CSV 报表 ./results2csv -p results > results.csv

结果默认存放在results目录下。更详细的参数说明见 doc/usage.md，命令行入口实现在 sb/cli.py。

九、进阶建议

• 想跑全部 25 款工具：把-t mythril换成-t all，但首次运行会拉取大量镜像，建议先用单工具验证环境
• 做批量分析：配合--processes N与--mem-limit控制资源占用，官方也提供make系列命令方便日常开发（见 Makefile）
• 追求全局部署：官方还提供了安装到/usr/local的全局方案，适合多人共用机器，详见 doc/installation.md

写在最后：SmartBugs 的跨平台安装本质是"装好 Docker + Python 3.10"，其余交给一键脚本。把本文的避坑表存下来，Windows 走 WSL2、macOS 注意芯片架构、Linux 别忘了 docker 组权限，你就能顺利迈出以太坊智能合约安全分析的第一步。祝分析顺利，漏洞全现形！🚀

【免费下载链接】smartbugsSmartBugs: A Framework to Analyze Ethereum Smart Contracts项目地址: https://gitcode.com/gh_mirrors/smar/smartbugs