oTree实验经济学工具零基础上手指南：从环境搭建到高级配置全攻略

问题导向：为什么选择oTree构建实验经济学研究平台？

在行为经济学研究中，研究者常常面临实验设计复杂、数据采集困难、实时交互实现繁琐等挑战。oTree作为一款专为实验经济学打造的开源框架，通过Python+Django技术栈实现了实验流程的可视化配置，支持多玩家实时互动场景，同时提供完善的数据记录与导出功能。本指南将帮助零基础用户快速掌握从环境搭建到高级配置的全流程，避开90%的常见坑点。

核心优势解析：技术选型背后的决策逻辑

oTree采用现代化技术组合，在保证性能的同时大幅降低开发门槛，以下是其核心技术栈的对比分析：

技术组件	功能作用	选型优势	传统方案对比
Python 3.6+	核心编程语言	语法简洁易读，科学计算库丰富	MATLAB需额外编程，实验逻辑实现复杂
Django	Web应用框架	内置ORM和管理后台，快速开发	纯Flask需手动配置路由和模板系统
Channels	WebSocket支持	实现玩家间实时通信	传统HTTP轮询延迟高，资源消耗大
Bootstrap	前端框架	响应式设计，适配多终端	自定义CSS开发周期长，兼容性问题多
MySQL	数据库系统	事务支持，数据一致性保障	SQLite不适合多用户并发场景

表：oTree核心技术栈对比分析

环境准备：从零开始的系统配置

系统兼容性检查

在开始安装前，请确认您的系统满足以下要求：

• 兼容Python 3.6+系列版本（推荐3.8-3.10）
• 已安装pip包管理器（Python 3.4+默认包含）
• 可用的MySQL 5.7+或MariaDB 10.2+数据库服务
• 网络连接（用于获取项目代码和依赖包）

🔧 检查点：打开终端执行以下命令验证基础环境

python --version  # 应显示3.6.0及以上版本
pip --version     # 应显示19.0及以上版本
mysql --version   # 应显示5.7.0及以上版本

依赖项预安装

不同操作系统需安装的系统依赖有所区别：

Ubuntu/Debian系统：

sudo apt update && sudo apt install -y python3-dev libmysqlclient-dev gcc

CentOS/RHEL系统：

sudo yum install -y python3-devel mysql-devel gcc

macOS系统（需先安装Homebrew）：

brew install mysql-connector-c

⚠️ 故障排除：若出现"mysql_config not found"错误，需将MySQL路径添加到环境变量：

export PATH=$PATH:/usr/local/mysql/bin  # 根据实际安装路径调整

核心安装：三步完成框架部署

阶段1：获取项目代码

通过Git工具克隆官方仓库到本地工作目录：

git clone https://gitcode.com/gh_mirrors/otr/oTree
cd oTree  # 进入项目根目录

✅ 预期结果：当前目录应包含以下关键文件：

oTree/
├── requirements.txt  # 项目依赖清单
├── settings.py       # 主配置文件
└── manage.py         # Django命令行工具

阶段2：创建虚拟环境与依赖安装

为避免系统环境冲突，建议使用虚拟环境隔离项目依赖：

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境（Windows使用venv\Scripts\activate）
source venv/bin/activate

# 安装依赖包（添加--no-cache-dir解决缓存问题）
pip install --no-cache-dir -r requirements.txt

⚠️ 故障排除：若安装channels时出现编译错误，需安装额外系统依赖：

# Ubuntu/Debian
sudo apt install -y libssl-dev libffi-dev python3-setuptools

# CentOS/RHEL
sudo yum install -y openssl-devel libffi-devel

阶段3：数据库配置与初始化

1. 创建数据库：登录MySQL终端执行以下SQL：

CREATE DATABASE otree_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'otree_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON otree_db.* TO 'otree_user'@'localhost';
FLUSH PRIVILEGES;

2. 修改配置文件：编辑项目根目录下的settings.py文件：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'otree_db',          # 数据库名
        'USER': 'otree_user',        # 用户名
        'PASSWORD': 'your_secure_password',  # 密码
        'HOST': 'localhost',         # 数据库地址
        'PORT': '3306',              # 端口号
        'OPTIONS': {
            'charset': 'utf8mb4',
        }
    }
}

3. 执行数据库迁移：

python manage.py migrate  # 创建数据表结构
python manage.py createsuperuser  # 创建管理员账户（按提示输入信息）

✅ 验证数据库连接：执行以下命令检查数据库状态：

python manage.py check  # 应显示"System check identified no issues (0 silenced)."

验证与排错：开发服务器启动与测试

启动开发服务器

在项目根目录执行：

python manage.py runserver  # 默认监听127.0.0.1:8000

打开浏览器访问http://127.0.0.1:8000，应看到oTree的欢迎页面。使用之前创建的管理员账户登录后台（http://127.0.0.1:8000/admin）。

常见启动问题排查

错误现象	可能原因	解决方案
端口被占用	8000端口已被其他程序使用	使用python manage.py runserver 8001指定其他端口
数据库连接失败	配置文件参数错误	检查settings.py中的数据库连接信息
静态文件无法加载	开发服务器未处理静态文件	执行python manage.py collectstatic

常见场景配置：从基础到高级应用

多实验并行设置

oTree支持在同一平台运行多个独立实验，通过以下步骤实现：

1. 创建新实验应用：

python manage.py startapp my_experiment  # 创建实验应用

2. 在settings.py中注册应用：

INSTALLED_APPS = [
    # ... 原有应用 ...
    'my_experiment',  # 添加新实验应用
]

3. 配置实验会话：在settings.py中设置：

SESSION_CONFIGS = [
    {
        'name': 'public_goods',
        'display_name': '公共物品博弈实验',
        'num_demo_participants': 3,
        'app_sequence': ['public_goods_simple'],
    },
    {
        'name': 'my_experiment',  # 新实验配置
        'display_name': '我的自定义实验',
        'num_demo_participants': 2,
        'app_sequence': ['my_experiment'],
    },
]

数据导出方案

oTree提供多种数据导出方式，满足不同分析需求：

1. 后台导出：通过管理员界面（/admin）的"Export data"功能导出CSV/Excel格式数据

2. 命令行导出：

# 导出所有实验数据
python manage.py exportdata --all --output=all_data.csv

# 导出特定实验数据
python manage.py exportdata --app=public_goods_simple --output=public_goods_data.csv

3. 自定义导出脚本：创建export_custom.py文件：

from otree.models import Session
import pandas as pd

session = Session.objects.get(code='your_session_code')
data = session.get_subsession().get_players().values(
    'id_in_group', 'contribution', 'payoff'
)
pd.DataFrame(list(data)).to_csv('custom_data.csv', index=False)

进阶资源：持续学习与社区支持

官方文档与示例

• 核心文档：项目根目录下的docs/文件夹
• 示例实验：public_goods_simple/、dictator/等目录包含完整实验代码

社区支持渠道

• 问题讨论：通过项目的Issue系统提交技术问题
• 经验分享：查看_rooms/econ101.txt中的教学案例
• 代码贡献：通过Pull Request参与功能改进

性能优化建议

• 生产环境使用Gunicorn作为WSGI服务器：

pip install gunicorn
gunicorn otree.wsgi:application --workers=4 --bind=0.0.0.0:8000

• 启用数据库连接池：在settings.py中添加：

DATABASES['default']['CONN_MAX_AGE'] = 60  # 连接保持60秒

通过本指南的步骤，您已完成oTree框架的完整配置。无论是简单的决策实验还是复杂的多玩家互动场景，oTree都能提供稳定可靠的技术支持，帮助您将研究想法快速转化为可执行的实验方案。