零门槛上手oTree：实验经济学工具安装避坑指南

oTree是一款基于Python的经济学实验平台，专为研究人员设计的开源工具，能够快速搭建和运行各类在线行为实验。本指南将帮助新手用户避开常见陷阱，从零开始完成oTree环境的搭建与配置，让你轻松开启实验经济学研究之旅。

项目核心解析

技术栈概览

技术名称	作用	版本要求
Python	主要编程语言	3.6+
Django	Python Web开发框架	兼容最新稳定版
Channels	Django的WebSocket扩展库	兼容Django版本
Bootstrap	前端响应式布局框架	最新稳定版
MySQL	关系型数据库管理系统	5.7+

oTree基于Django框架构建，通过Channels实现实时通信功能，使用Bootstrap确保实验界面在各种设备上都能良好展示，而MySQL则负责安全存储实验数据。这种技术组合既保证了开发效率，又能满足实验经济学研究对数据准确性和系统稳定性的要求。

环境搭建全流程

环境检查清单

在开始安装前，请确保你的系统满足以下条件：

• 已安装Python 3.6或更高版本
• 具备pip包管理器（通常随Python一同安装）
• 已安装MySQL数据库服务器
• 拥有git版本控制工具
• 稳定的网络连接（用于下载依赖包）

✅ 验证Python版本：

python --version

✅ 验证pip版本：

pip --version

依赖项安装指南

Python环境配置

如果你的系统尚未安装Python，可以通过官方网站下载安装包。Windows用户建议勾选"Add Python to PATH"选项，macOS用户可使用Homebrew安装，Linux用户通常系统已预装Python。

MySQL数据库安装

根据你的操作系统选择合适的MySQL版本进行安装：

• Windows：下载MySQL Installer
• macOS：使用Homebrew执行brew install mysql
• Linux：通过系统包管理器安装（如apt install mysql-server）

安装完成后，确保MySQL服务已启动并设置了root密码。

安装步骤详解

步骤1：获取项目代码

目标：将oTree源代码下载到本地 操作：

git clone https://gitcode.com/gh_mirrors/otr/oTree
cd oTree

验证：检查当前目录是否包含requirements.txt和settings.py文件

ls | grep -E "requirements.txt|settings.py"

步骤2：安装项目依赖

目标：配置Python虚拟环境并安装所需依赖包 操作：

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install -r requirements.txt

验证：检查关键包是否安装成功

pip list | grep -E "django|channels|mysqlclient"

步骤3：数据库配置

目标：创建数据库并配置连接信息 操作：

mysql -u root -p
CREATE DATABASE otree_db CHARACTER SET utf8mb4;
exit

编辑settings.py文件，修改数据库配置部分：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'otree_db',
        'USER': 'root',
        'PASSWORD': '你的数据库密码',
        'HOST': 'localhost',
        'PORT': '3306',
    }
}

验证：测试数据库连接

python -c "import django; django.db.connection.ensure_connection()"

步骤4：初始化数据库

目标：创建必要的数据表结构 操作：

python manage.py migrate

验证：检查是否有错误信息输出，成功会显示"Applied"字样

步骤5：启动开发服务器

目标：运行oTree应用并访问管理界面 操作：

python manage.py runserver

验证：打开浏览器访问http://127.0.0.1:8000/，应该能看到oTree的欢迎页面

常见问题速查

问题1：数据库连接失败

错误提示：django.db.utils.OperationalError: (2002, "Can't connect to MySQL server on 'localhost'") 解决方案：

1. 检查MySQL服务是否已启动：systemctl status mysql（Linux）或在服务管理器中查看
2. 确认数据库用户名和密码是否正确
3. 尝试使用127.0.0.1代替localhost作为数据库主机地址

问题2：依赖包安装错误

错误提示：error: command 'x86_64-linux-gnu-gcc' failed 解决方案： 安装系统依赖库：

sudo apt-get install python3-dev default-libmysqlclient-dev build-essential

然后重新运行pip install -r requirements.txt

问题3：migrate命令执行失败

错误提示：django.db.utils.ProgrammingError: (1049, "Unknown database 'otree_db'") 解决方案：

1. 确认已创建数据库：mysql -u root -p -e "SHOW DATABASES;"
2. 如果数据库不存在，重新执行创建数据库命令
3. 检查settings.py中的数据库名称是否与创建的数据库名称一致

总结

通过本指南，你已经成功搭建了oTree实验经济学平台的开发环境。现在你可以开始创建自己的经济学实验，探索人类决策行为的奥秘。如果在使用过程中遇到其他问题，可以查阅项目文档或加入oTree社区寻求帮助。祝你在实验经济学研究中取得丰硕成果！