⚠️ 重要警告：不要在 Windows 下编译 ESP-IDF 项目！

Windows 下 ESP-IDF 的编译环境配置复杂，串口驱动兼容性差，路径分隔符问题多，强烈建议在 Ubuntu 原生系统 或 WSL2 中操作。

环境信息

一、换源（清华源）

sudo vi /etc/apt/sources.list

写入以下内容：

# 默认注释了源码镜像以提高 apt update 速度，如有需要可自行取消注释
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble main restricted universe multiverse
# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-updates main restricted universe multiverse
# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-backports main restricted universe multiverse
# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-backports main restricted universe multiverse

# 以下安全更新软件源为官方源配置
deb http://security.ubuntu.com/ubuntu/ noble-security main restricted universe multiverse
# deb-src http://security.ubuntu.com/ubuntu/ noble-security main restricted universe multiverse

# 预发布软件源，不建议启用
# deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-proposed main restricted universe multiverse
# # deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-proposed main restricted universe multiverse

更新：

sudo apt update

二、安装依赖工具

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

三、获取 ESP-IDF v5.5.4

3.1 创建文件夹

mkdir -p ~/esp
cd ~/esp

3.2 使用 esp-gitee-tools 加速

git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git
cd esp-gitee-tools
./jihu-mirror.sh set
cd ..

3.3 拉取 ESP-IDF v5.5.4

git clone --recursive -b v5.5.4 https://github.com/espressif/esp-idf.git

3.4 ESP-IDF 工程目录结构

安装完毕后，可以查看 esp-idf 文件目录：

cd esp-idf
ls

主要目录说明：

3.5 安装编译工具链

cd ~/esp/esp-idf
export IDF_GITHUB_ASSETS="dl.espressif.cn/github_assets"
./install.sh

3.6 配置环境变量

方法一：每次手动加载（推荐）

# 编辑 ~/.bashrc
sudo vi ~/.bashrc

# 在文件末尾添加
alias get_idf='. $HOME/esp/esp-idf/export.sh'

# 刷新配置
source ~/.bashrc

之后每次打开终端，运行 get_idf 即可加载 ESP 环境。

方法二：永久加载

# 编辑 ~/.profile
sudo vi ~/.profile

# 在文件末尾添加
source ~/esp/esp-idf/export.sh

四、克隆并编译 MimicLaw

4.1 克隆项目

cd ~/esp
git clone https://github.com/ixbaicn/mimiclaw.git
cd mimiclaw

4.2 设置目标芯片

idf.py set-target esp32s3

4.3 编译

idf.py fullclean && idf.py build

五、烧录到 ESP32-S3

5.1 查找串口

ls /dev/ttyACM*
ls /dev/ttyUSB*

5.2 烧录并监视

idf.py -p /dev/ttyACM0 flash monitor

退出监视按 Ctrl + ]。

六、ESP-IDF 常用命令

查看支持的芯片类型：

idf.py --list-targets

七、Ubuntu 黑屏解决办法

一键修复

sudo sed -i 's/#WaylandEnable=false/WaylandEnable=false/' /etc/gdm3/custom.conf && \
sudo mkdir -p /etc/systemd/system/user@.service.d/ && \
echo -e "[Service]\nDelegate=yes\nTasksMax=infinity" | sudo tee /etc/systemd/system/user@.service.d/override.conf && \
sudo systemctl daemon-reload && \
systemctl --user mask tracker-miner-fs-3 tracker-extract-3 tracker-miner-apps 2>/dev/null && \
sudo systemctl mask geoclue.service 2>/dev/null && \
echo "修复完成，重启中..." && \
sudo reboot

关闭自动锁屏

gsettings set org.gnome.desktop.screensaver lock-enabled false
gsettings set org.gnome.desktop.session idle-delay 0

关闭自动挂起（服务器用）

sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

八、注意事项

九、效果图

烧录成功效果：

八、参考资料

✅ 完成！ 烧录成功后，ESP32-S3 会自动连接 WiFi，你就能在飞书/Telegram 上跟你的 AI 助手对话了！