安裝參考
本文是安裝方式的完整參考（pip / uv / Docker / 故障排除）。 如果你只想快速上手，5 分鐘快速入門 已經涵蓋了最簡流程。
系統要求
- Python 3.10 或更高版本
- pip 或 uv（推薦）
- 足夠的磁碟空間（至少 100MB）
安裝方式
方式一：使用 pip 安裝
# 安裝 ErisPulse
pip install ErisPulse
# 升級到最新版本
pip install ErisPulse --upgrade
方式二：使用 uv 安裝（推薦）
uv 是一個更快的 Python 工具鏈，推薦用於開發環境。
安裝 uv
# 使用 pip 安裝 uv
pip install uv
# 驗證安裝
uv --version
建立虛擬環境
# 建立專案資料夾
mkdir my_bot && cd my_bot
# 安裝 Python 3.12
uv python install 3.12
# 建立虛擬環境
uv venv
激活虛擬環境
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate
安裝 ErisPulse
# 安裝 ErisPulse
uv pip install ErisPulse --upgrade
方式三：使用 uv tool 安裝（全域 CLI，推薦）
如果只想將 epsdk 當作全域命令列工具使用，uv tool install 是最乾淨的方式——
epsdk 在獨立的工具環境中運行，不會污染任何專案環境：
# 安裝（epsdk 立即可用，無需激活任何虛擬環境）
uv tool install ErisPulse
# 升級（或直接使用 epsdk self-update，會自動走此通道）
uv tool upgrade ErisPulse
Note
工具環境中的 epsdk 在專案資料夾內運行時會自動感知專案 .venv：
epsdk install 將元件安裝進專案環境、epsdk run 使用專案環境運行機器人，
框架本體仍由工具環境提供，兩邊互不干擾。
項目初始化與模組安裝
安裝完成後，項目初始化、模組安裝、運行的完整流程見 5 分鐘快速開始。
方式三：使用 ErisPulse-App 客戶端（免終端）
不想安裝 Python 環境？ErisPulse-App 是官方全平台客戶端 （Android / Windows / Linux / macOS），手機直接運行，桌面版支援最小化到 系統托盤後台常駐；內建 Python 運行時與 ErisPulse SDK，無需終端與手動配置：
- 從 GitHub Releases 按平台選擇下載
（Android
online/offlineAPK、Windowssetup.exe/zip、Linuxtar.gz、macOSzip） - 在 App 內建立並啟動實例，透過原生介面管理適配器與模組、瀏覽模組商店
完整說明見 ErisPulse-App 安裝與使用。
驗證安裝
檢查安裝
# 檢查 ErisPulse 版本
epsdk --version
執行測試
# 執行項目
epsdk run main.py
如果看到類似的輸出，表示安裝成功：
[INFO] 正在初始化 ErisPulse...
[INFO] 適配器已載入: Yunhu
[INFO] 模組已載入: MyModule
[INFO] ErisPulse 初始化完成
常見問題
安裝失敗
- 檢查 Python 版本是否 >= 3.10（推薦 3.10 - 3.14；3.14t free-threaded 無 GIL 建構暫未列入正式支援，框架以實驗性 CI 冒煙持續監測）
- 嘗試使用
uv pip install ErisPulse替代pip install - 如果提示權限錯誤，嘗試
pip install --user ErisPulse或使用虛擬環境 - 如果在企業代理環境下遇到 SSL 證書錯誤，嘗試
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org ErisPulse - 確保網路連接正常，pip 源可訪問
配置錯誤
- 檢查
config.toml語法是否正確（TOML 格式對縮進和引號敏感） - 確認所有必需的配置項都已填寫
- 查看終端日誌獲取詳細錯誤資訊
- 使用
epsdk init重新生成配置檔案
模組安裝失敗
- 確認模組名稱拼寫正確（大小寫敏感）
- 檢查網路連接
- 使用
epsdk list-remote查看可用模組列表 - 確認模組與你目前 SDK 版本相容
Windows PowerShell 執行策略
如果 PowerShell 提示「無法載入檔案...因為在此系統上禁止執行腳本」：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Debian/Ubuntu 虛擬環境建立失敗
如果安裝腳本提示「虛擬環境建立失敗」，且錯誤資訊包含 ensurepip is not available，是因為 Debian/Ubuntu 預設未安裝 python3-venv（系統 Python 的 ensurepip 被禁用）：
sudo apt install python3.13-venv # 按實際 Python 版本安裝對應套件
# 或安裝通用元套件：
sudo apt install python3-venv
安裝後重新執行安裝腳本即可。新版安裝腳本在偵測到該問題時會主動詢問並嘗試自動安裝對應系統套件；也可以改用 uv（uv venv 不依賴 ensurepip）。