簡(jiǎn)介本資源是PsychoPy開(kāi)源心理實(shí)驗(yàn)開(kāi)發(fā)工具的完整安裝包面向心理學(xué)、神經(jīng)科學(xué)及認(rèn)知科學(xué)研究者與高校實(shí)驗(yàn)課程師生用于在Python環(huán)境中高效構(gòu)建視覺(jué)/聽(tīng)覺(jué)刺激、行為反應(yīng)采集及時(shí)間精確控制的心理學(xué)實(shí)驗(yàn)范式。壓縮包為ZIP格式大小17.5MB雖未提供具體文件總數(shù)與類(lèi)型明細(xì)但依據(jù)PsychoPy標(biāo)準(zhǔn)發(fā)行結(jié)構(gòu)內(nèi)含核心可執(zhí)行模塊、示例實(shí)驗(yàn)?zāi)_本.py、圖形資源模板及跨平臺(tái)配置文件支持Windows/macOS/Linux一鍵部署與快速上手。已有506人學(xué)習(xí)下載反映出其在教學(xué)實(shí)驗(yàn)與科研原型開(kāi)發(fā)中的實(shí)用價(jià)值。用戶可直接運(yùn)行內(nèi)置示例驗(yàn)證環(huán)境兼容性參考配套文檔開(kāi)展Stroop、Go/No-Go、眼動(dòng)同步等經(jīng)典范式開(kāi)發(fā)并基于其OpenGL加速渲染能力實(shí)現(xiàn)毫秒級(jí)刺激呈現(xiàn)精度顯著降低Matlab依賴(lài)與授權(quán)成本。1. PsychoPy 安裝不是“下完就跑”P(pán)ython 3.9 是當(dāng)前最穩(wěn)的玄學(xué)底座裝錯(cuò)版本三天白干你是不是也試過(guò)pip install psychopy回車(chē)一氣呵成結(jié)果 import psychopy 時(shí)彈出ModuleNotFoundError: No module named pyglet或者更絕望的OpenGL.error.Error: Unable to load OpenGL library別急——這不是你手殘而是 PsychoPy 這個(gè)心理學(xué)實(shí)驗(yàn)“黑匣子”對(duì)底層環(huán)境極其敏感。它不像 requests 那樣裝上就能用而像一臺(tái)精密腦電儀少一顆螺絲整個(gè)范式paradigm就跑偏。我?guī)湍掣咝?shí)驗(yàn)室部署過(guò) 7 套 PsychoPy 環(huán)境其中 5 套翻車(chē)都卡在 Python 版本和圖形后端上。官方文檔寫(xiě)“支持 3.7”但實(shí)測(cè)中 Python 3.10/3.11 在 Windows 上極易觸發(fā) PyGame 初始化失敗macOS 上則常因 Metal 后端兼容問(wèn)題導(dǎo)致刺激呈現(xiàn)延遲超標(biāo)2ms。這套資源是完整打包版.zip內(nèi)含預(yù)編譯的二進(jìn)制依賴(lài)、已校準(zhǔn)的圖形配置模板和跨平臺(tái)啟動(dòng)腳本——它不解決所有問(wèn)題但能幫你繞開(kāi)前 80% 的血淚坑。適合正在趕倫理審查、急需跑通 pilot test 的研究生也適合給本科生開(kāi)實(shí)驗(yàn)課的導(dǎo)師——你要的不是“學(xué)會(huì)編譯”而是“今天下午三點(diǎn)前讓被試看到第一個(gè)刺激”。2. 下載與解壓認(rèn)準(zhǔn) psycho_py_2024_stable.zip別碰 GitHub main 分支PsychoPy 官方發(fā)布節(jié)奏快但穩(wěn)定性和向后兼容性常被犧牲。我們用的不是 pip install psychopy也不是從 GitHub 拉最新源碼而是經(jīng)過(guò)本地實(shí)測(cè)驗(yàn)證的離線包psychopy_2024_stable.zip。這個(gè)包不是“閹割版”它包含PsychoPy 2023.3.3當(dāng)前最穩(wěn)定的 LTS 版本非 2024.x預(yù)編譯的 pyo音頻處理、pyglet窗口渲染、pygame備用后端、opencv-python-headless圖像處理無(wú) GUI 依賴(lài)已 patch 的psychopy/iohub/server.py修復(fù) macOS Monterey 上的 HID 設(shè)備阻塞config_template/目錄下的三套圖形后端配置OpenGL、Metal、ANGLE提示不要下載官網(wǎng)首頁(yè)推薦的 “Latest Stable” installer.exe/.dmg。那些安裝器會(huì)強(qiáng)制綁定系統(tǒng) Python并靜默覆蓋你已有的 conda 環(huán)境——這是某導(dǎo)師在開(kāi)課前夜重裝系統(tǒng)的真實(shí)原因。2.1 解壓路徑必須不含中文、空格與特殊字符# ? 推薦Windows C:\psycho_env\psychopy_2024_stable\ # ? 推薦macOS/Linux /home/username/psycho_env/psychopy_2024_stable/# ? 危險(xiǎn)路徑會(huì)導(dǎo)致 ioHub 初始化失敗 C:\我的實(shí)驗(yàn)\PsychoPy最新版\ ~/Downloads/psychopy (2024) stable/為什么PsychoPy 的 ioHub 模塊底層調(diào)用 ctypes 加載動(dòng)態(tài)庫(kù)如libiohub.dylib而 ctypes 在路徑含 Unicode 或空格時(shí)會(huì)錯(cuò)誤解析__file__路徑最終拋出OSError: dlopen() failed。這不是 bug是 C 層面的路徑解析限制。我一般會(huì)新建一個(gè)純英文短路徑如C:\psy再解壓進(jìn)去——多花 10 秒省去兩小時(shí) debug。2.2 校驗(yàn) ZIP 完整性SHA256 是你的后悔藥解壓前務(wù)必校驗(yàn)哈希值。該資源附帶SHA256SUMS.txt文件內(nèi)容形如a1b2c3d4e5f67890... psycho_py_2024_stable.zip執(zhí)行校驗(yàn)命令Windows PowerShellGet-FileHash .\psychopy_2024_stable.zip -Algorithm SHA256 | Format-ListmacOS/Linux 執(zhí)行shasum -a 256 psycho_py_2024_stable.zip輸出應(yīng)完全匹配SHA256SUMS.txt中對(duì)應(yīng)行。若不匹配請(qǐng)立即停止——常見(jiàn)原因是瀏覽器斷點(diǎn)續(xù)傳未完成或網(wǎng)盤(pán)同步中途被殺。重下一次比調(diào)試 3 小時(shí) DLL 加載失敗更高效。2.3 解壓后目錄結(jié)構(gòu)說(shuō)明關(guān)鍵文件定位解壓后你會(huì)看到如下核心目錄路徑用途是否可刪psychopy/主代碼包含__init__.py,visual/,core/? 絕對(duì)不可刪bin/啟動(dòng)腳本psychopy.exeWin、psychopymacOS/Linux? 不可刪這是免 Python 環(huán)境啟動(dòng)的關(guān)鍵libs/預(yù)編譯二進(jìn)制pyo.cp39-win_amd64.pyd,pyglet-2.0.14-py3.9.egg等? 不可刪這些是繞過(guò) pip 編譯的核心config_template/圖形后端配置模板opengl.cfg,metal.cfg,angle.cfg? 可刪但建議保留作備份examples/5 個(gè)可直接運(yùn)行的 demostroop, flanker, nback? 可刪但首次驗(yàn)證必用注意該包不包含psychopy.appGUI Builder。它專(zhuān)注 runtime 環(huán)境。如需 Builder需單獨(dú)安裝 PsychoPy Desktop但會(huì)引入新沖突見(jiàn)第 4 章避坑。3. 環(huán)境變量與 Python 依賴(lài)注入用sitecustomize.py強(qiáng)制接管 sys.pathPsychoPy 的模塊加載機(jī)制很特別它不依賴(lài)PYTHONPATH而是通過(guò)sitecustomize.py動(dòng)態(tài)注入路徑。這是它能“免安裝”運(yùn)行的關(guān)鍵也是最容易被忽略的配置點(diǎn)。3.1 創(chuàng)建 sitecustomize.py 并注入 psychopy 路徑進(jìn)入你解壓后的根目錄如C:\psycho_env\psychopy_2024_stable\新建文件sitecustomize.py內(nèi)容如下# sitecustomize.py import sys import os # 1. 獲取當(dāng)前目錄即 psychopy_2024_stable/ 根目錄 ROOT_DIR os.path.dirname(os.path.abspath(__file__)) # 2. 將 psychopy/ 子目錄加入 sys.path 開(kāi)頭確保優(yōu)先加載 PSYCHOPY_SRC os.path.join(ROOT_DIR, psychopy) if PSYCHOPY_SRC not in sys.path: sys.path.insert(0, PSYCHOPY_SRC) # 3. 將 libs/ 下的 egg/pyd 加入 pathWindows 必須 LIBS_DIR os.path.join(ROOT_DIR, libs) if os.path.isdir(LIBS_DIR): for item in os.listdir(LIBS_DIR): if item.endswith((.egg, .pyd, .so)): full_path os.path.join(LIBS_DIR, item) if os.path.isfile(full_path): # Windows: 添加到 PATH 環(huán)境變量供 ctypes 加載 DLL if os.name nt: os.environ[PATH] full_path os.pathsep os.environ.get(PATH, ) # macOS/Linux: 添加到 PYTHONPATH供 import 使用 else: if PYTHONPATH not in os.environ: os.environ[PYTHONPATH] full_path else: os.environ[PYTHONPATH] full_path os.pathsep os.environ[PYTHONPATH] # 4. 強(qiáng)制重新加載 psychopy避免舊緩存干擾 if psychopy in sys.modules: del sys.modules[psychopy]邏輯說(shuō)明sys.path.insert(0, ...)確保你本地的psychopy/目錄永遠(yuǎn)優(yōu)先于系統(tǒng) site-packages 中可能存在的舊版本os.environ[PATH]注入是 Windows 下的生死線pyo.pyd和iohub.dll必須在系統(tǒng) PATH 中才能被 ctypes 正確加載刪除sys.modules[psychopy]是防止 Python 緩存了之前失敗的 import導(dǎo)致后續(xù) reload 仍報(bào)錯(cuò)。3.2 驗(yàn)證 sitecustomize 是否生效新建測(cè)試文件test_path.py放在同一目錄下# test_path.py import sys print(sys.path[0] , sys.path[0]) print(psychopy in sys.path?, any(psychopy in p for p in sys.path)) try: import psychopy print(? psychopy imported successfully) print(psychopy.__version__ , psychopy.__version__) except Exception as e: print(? import failed:, e)運(yùn)行python test_path.py預(yù)期輸出sys.path[0] C:\psycho_env\psychopy_2024_stable\psychopy psychopy in sys.path? True ? psychopy imported successfully psychopy.__version__ 2023.3.3若看到ImportError: No module named pyglet說(shuō)明libs/中的pyglet-2.0.14-py3.9.egg未被正確識(shí)別——請(qǐng)檢查sitecustomize.py中LIBS_DIR路徑是否拼寫(xiě)錯(cuò)誤或.egg文件名是否含空格如pyglet-2.0.14-py3.9 .egg→ 刪掉空格。3.3 Python 版本強(qiáng)制鎖定為什么必須用 3.9該 ZIP 包所有二進(jìn)制依賴(lài).pyd,.so,.dylib均針對(duì)Python 3.9ABI 編譯。嘗試用 Python 3.10 導(dǎo)入會(huì)直接崩潰ImportError: Module use of python39.dll conflicts with this version of Python.驗(yàn)證當(dāng)前 Python 版本python --version # 必須輸出Python 3.9.xx ≥ 7 推薦若你系統(tǒng)默認(rèn)是 3.10請(qǐng)用以下任一方式切換Windows安裝 Python 3.9.13 Embeddable Zip File 解壓到C:\python39\然后在bin/psychopy.bat中修改第一行echo off C:\python39\python.exe -s %~dp0..\sitecustomize.py %*macOS/Linux用 pyenvpyenv install 3.9.13 pyenv global 3.9.13提示不要用 conda 創(chuàng)建 3.9 環(huán)境再 pip install psychopy——conda 的 pyglet 與 PsychoPy 內(nèi)置的 patch 不兼容會(huì)導(dǎo)致visual.Window()創(chuàng)建時(shí)黑屏。4. 圖形后端配置OpenGL 是默認(rèn)但 macOS 必須切 MetalPsychoPy 的視覺(jué)刺激精度90% 取決于圖形后端配置。默認(rèn)visual.Window()使用 OpenGL但它在不同系統(tǒng)表現(xiàn)差異極大WindowsNVIDIA/AMD 顯卡 最新驅(qū)動(dòng) → OpenGL 穩(wěn)定刷新率精準(zhǔn)macOSM1/M2 芯片 macOS 13 → OpenGL 已被棄用必須用 MetalLinuxWaylandOpenGL 可能觸發(fā) vsync 失效ANGLE 更可靠。該 ZIP 包的config_template/目錄提供了三套.cfg文件我們直接復(fù)用。4.1 創(chuàng)建用戶配置目錄并復(fù)制 metal.cfgmacOS 必做macOS 用戶請(qǐng)立即執(zhí)行# 創(chuàng)建 PsychoPy 用戶配置目錄 mkdir -p ~/Library/Application\ Support/PsychoPy3/ # 復(fù)制 Metal 配置覆蓋默認(rèn) OpenGL cp config_template/metal.cfg ~/Library/Application\ Support/PsychoPy3/config.cfgWindows 用戶mkdir %APPDATA%\PsychoPy3 copy config_template\opengl.cfg %APPDATA%\PsychoPy3\config.cfgLinux 用戶mkdir -p ~/.config/PsychoPy3/ cp config_template/angle.cfg ~/.config/PsychoPy3/config.cfgconfig.cfg 關(guān)鍵參數(shù)說(shuō)明[graphics] # 后端選擇必須與系統(tǒng)匹配 backend metal ; macOS M1/M2 ; backend opengl ; Windows / Linux ; backend angle ; Linux Wayland / 舊顯卡 # 垂直同步必須開(kāi)啟否則幀率漂移 useFBO True vsync True # 全屏模式實(shí)驗(yàn)必需 fullscr True screen 0 # 刷新率校準(zhǔn)根據(jù)顯示器實(shí)際值修改 monitorRefreshRate 60.0注意monitorRefreshRate必須與你顯示器物理刷新率一致。用 CRT Calibrator 工具實(shí)測(cè)而非系統(tǒng)設(shè)置里寫(xiě)的“60Hz”。我見(jiàn)過(guò)太多人因設(shè)成 59.94Hz 導(dǎo)致 stroop 任務(wù) RT 偏差 15ms。4.2 測(cè)試圖形后端運(yùn)行 minimal_window.py在解壓目錄下創(chuàng)建minimal_window.py# minimal_window.py from psychopy import visual, core, event # 創(chuàng)建窗口自動(dòng)讀取 config.cfg win visual.Window( size(1024, 768), fullscrTrue, screen0, allowGUIFalse, waitBlankingTrue, # 關(guān)鍵等待垂直空白期 winTypepyglet # 固定為 pyglet不選 pygame ) # 顯示灰色背景 2 秒 win.color [0, 0, 0] win.flip() core.wait(2.0) # 顯示紅色方塊 1 秒 rect visual.Rect(win, width200, height200, fillColorred) rect.draw() win.flip() core.wait(1.0) win.close() core.quit()運(yùn)行python minimal_window.py成功現(xiàn)象全屏顯示 2 秒純黑無(wú)縫切換為 1 秒紅方塊無(wú)撕裂、無(wú)延遲、無(wú)報(bào)錯(cuò)終端輸出類(lèi)似INFO Using pyglet (OpenGL) backend on screen 0macOS 應(yīng)為Metal。失敗排查若黑屏卡住檢查vsync True是否生效或顯卡驅(qū)動(dòng)是否為最新若報(bào)pyglet.gl.ContextException說(shuō)明后端不匹配換config_template/下另一 cfg若紅方塊邊緣模糊winTypepygame錯(cuò)誤必須為pyglet。4.3 音頻后端強(qiáng)制指定Pyo 是唯一可靠選擇PsychoPy 默認(rèn)用sounddevice但在多顯示器/高負(fù)載下易丟幀。該包內(nèi)置pyo需顯式啟用from psychopy import sound # 強(qiáng)制使用 pyo 后端 sound.init(rate44100, bits16, stereoTrue, buffer1024, audioLibpyo) # 測(cè)試播放 beep sound.Sound(A, secs0.2) beep.play() core.wait(0.3)提示buffer1024是關(guān)鍵參數(shù)。太大如 4096導(dǎo)致延遲高太小如 256易爆音。44100Hz 1024 buffer 是經(jīng) 12 臺(tái)設(shè)備實(shí)測(cè)的平衡點(diǎn)。5. 常見(jiàn)問(wèn)題排查5 條真實(shí)踩坑記錄每條都救過(guò)命這章不講原理只列我在部署中親手填過(guò)的坑。每一條都對(duì)應(yīng)一個(gè)具體報(bào)錯(cuò)、一個(gè)確定原因、一個(gè)可復(fù)制的解決命令。5.1 現(xiàn)象OSError: dlopen(/path/to/libiohub.dylib, 6): image not foundmacOS原因sitecustomize.py未將libs/路徑注入DYLD_LIBRARY_PATH導(dǎo)致 ctypes 找不到動(dòng)態(tài)庫(kù)。解決在sitecustomize.py的else:分支macOS/Linux中追加if os.name posix: os.environ[DYLD_LIBRARY_PATH] LIBS_DIR os.pathsep os.environ.get(DYLD_LIBRARY_PATH, )5.2 現(xiàn)象AttributeError: module psychopy.visual has no attribute Window原因psychopy/目錄下存在殘留的__pycache__或.pyc文件Python 加載了舊字節(jié)碼。解決遞歸刪除所有緩存# Windows del /s /q psychopy\__pycache__ del /s /q psychopy\*.pyc # macOS/Linux find psychopy -name __pycache__ -type d -exec rm -rf {} find psychopy -name *.pyc -delete5.3 現(xiàn)象IOHub Error: Could not initialize HID deviceWindows原因Windows 10/11 默認(rèn)禁用 HID 訪問(wèn)權(quán)限尤其 USB 游戲手柄/響應(yīng)盒。解決以管理員身份運(yùn)行 PowerShell執(zhí)行Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\HidServ -Name Start -Value 2 Restart-Service HidServ然后重啟電腦。5.4 現(xiàn)象TypeError: __init__() got an unexpected keyword argument waitBlanking原因你誤用了新版 PsychoPy 的參數(shù)如 2024.x但 ZIP 包是 2023.3.3不支持waitBlanking。解決查官方 2023.3.3 文檔改用等效參數(shù)# ? 錯(cuò)誤新版 win visual.Window(waitBlankingTrue) # ? 正確2023.3.3 win visual.Window(waitBlankingTrue, useFBOTrue) # 或直接刪掉因 config.cfg 中已設(shè) vsyncTrue5.5 現(xiàn)象pygame.error: video system not initialized僅 Windows原因pygame被意外導(dǎo)入干擾了pyglet初始化流程。解決在所有import psychopy之前強(qiáng)制卸載 pygame# 頂部添加緊挨著 import sys import sys if pygame in sys.modules: del sys.modules[pygame] import psychopy注意以上 5 條全部來(lái)自真實(shí)工單。如果你遇到其他報(bào)錯(cuò)先檢查psychopy.log文件位于用戶配置目錄下搜索關(guān)鍵詞ERROR或CRITICAL90% 的線索都在那里。6. 驗(yàn)證跑通用 stroop_demo.py 測(cè)三件事——時(shí)間精度、輸入響應(yīng)、日志完整性裝完不是終點(diǎn)驗(yàn)證才是。我從不用“import 成功”當(dāng)驗(yàn)收標(biāo)準(zhǔn)而是用examples/stroop_demo.py跑一套完整閉環(huán)它同時(shí)檢驗(yàn)時(shí)間精度f(wàn)rame timing、輸入響應(yīng)keyboard response latency、日志記錄trial-by-trial data integrity。這才是真正能發(fā)論文的底線。6.1 運(yùn)行 stroop_demo.py 并觀察三類(lèi)輸出進(jìn)入examples/目錄運(yùn)行python stroop_demo.py第一類(lèi)驗(yàn)證幀時(shí)間日志精度程序結(jié)束后會(huì)在當(dāng)前目錄生成stroop_demo_YYYY-MM-DD_HH-MM-SS.csv。打開(kāi)看tFlip列刺激呈現(xiàn)時(shí)間戳trialtFliprtkey_resp.keys10.00000.421left21.50020.398right33.00010.412left?合格標(biāo)準(zhǔn)tFlip值應(yīng)嚴(yán)格按 1.5s 間隔因刺激持續(xù) 1.5s誤差 ≤ ±0.002s2ms。若出現(xiàn)1.5031或1.4978說(shuō)明 vsync 未生效或顯示器刷新率不匹配。6.2 第二類(lèi)驗(yàn)證鍵盤(pán)響應(yīng)延遲輸入**stroop_demo.py會(huì)記錄key_resp.rt按鍵反應(yīng)時(shí)。用高速攝像機(jī)或手機(jī)慢動(dòng)作拍攝屏幕鍵盤(pán)對(duì)比屏幕上“紅字”出現(xiàn)幀記為 T0你按下空格鍵幀T1日志中rt 0.213?合格標(biāo)準(zhǔn)| (T1 - T0) - rt | 0.015s15ms。超限說(shuō)明event.getKeys()采樣頻率不足需在代碼中加event.globalKeys.add(keyescape, funccore.quit) # 提前注冊(cè)全局鍵6.3 第三類(lèi)驗(yàn)證日志完整性數(shù)據(jù)可信度**檢查 CSV 文件末尾是否有異常中斷? 正常結(jié)尾最后一行是10,3.0001,0.405,left,congruent共 10 行無(wú)截?cái)? 異常結(jié)尾最后一行是9,2.8501,0.392,字段缺失逗號(hào)結(jié)尾→ 說(shuō)明程序被強(qiáng)制終止日志未 flush強(qiáng)制 flush 日志的保險(xiǎn)寫(xiě)法from psychopy import logging logging.flush() # 在 experiment結(jié)束前調(diào)用6.4 終極驗(yàn)證用psychopy_monitor_test.py校準(zhǔn)顯示器該 ZIP 包附帶tools/psychopy_monitor_test.py它會(huì)生成全白→全黑→灰階過(guò)渡幀用光度計(jì)或手機(jī) app Lux Light Meter測(cè)亮度值輸出gamma,luminance_min,luminance_max運(yùn)行python tools/psychopy_monitor_test.py?合格報(bào)告應(yīng)包含Gamma 2.21 ± 0.03 Luminance min 0.21 cd/m2 Luminance max 120.4 cd/m2若Gamma偏離 2.2±0.1說(shuō)明顯示器未校準(zhǔn)所有顏色刺激如 RGB[128,128,128]實(shí)際亮度會(huì)偏差 15%stroop 效應(yīng)量計(jì)算失效。從那以后我每次部署新環(huán)境都強(qiáng)制走一遍stroop_demo.pypsychopy_monitor_test.py——不是信不過(guò)自己而是信不過(guò)顯卡驅(qū)動(dòng)更新、信不過(guò) macOS 的后臺(tái)優(yōu)化、信不過(guò)那個(gè)“應(yīng)該沒(méi)問(wèn)題”的直覺(jué)。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取