qmkfm/qmk_firmware

QMK Firmware 编译与开发环境

镜像概述

本镜像基于 Quantum Mechanical Keyboard (QMK) Firmware 项目构建，提供了一套完整的键盘固件编译与开发环境。QMK 是一款基于 tmk_keyboard 的开源键盘固件，专为 Atmel AVR 和 ARM 控制器设计，广泛支持 OLKB、ErgoDox EZ、Clueboard 等知名客制化键盘产品线。通过本镜像，开发者无需在本地配置复杂的交叉编译工具链，即可轻松完成固件的编译与构建。

核心功能和特性

• 广泛的硬件支持：原生支持 Atmel AVR 和 ARM 控制器，适配多种主流微控制器架构。
• 丰富的键盘适配：内置对 Planck、Preonic、ErgoDox EZ、Clueboard、Cluepad、Atreus 等键盘的支持，并包含庞大的社区键盘库。
• 完整的工具链：预装 AVR-GCC、ARM-GCC 及 QMK CLI 等编译和调试工具，开箱即用。
• 高度可定制：支持复杂的键位映射、宏定义、RGB 灯光控制、分层逻辑及多种高级键盘功能。

使用场景和适用范围

• 客制化键盘开发者：需要编写、修改和编译自定义键盘固件的硬件或软件开发者。
• 键盘爱好者：希望为自己的 QMK 兼容键盘刷入个性化配置（如修改键位、添加宏命令）的玩家。
• CI/CD 流水线：用于自动化构建、测试和发布键盘固件的持续集成环境。

详细的使用方法和配置说明

目录挂载

在使用本镜像编译固件时，建议将本地的 QMK 固件源码目录挂载到容器内的 /qmk_firmware 目录，以便在宿主机直接查看和提取编译生成的 .hex 或 .bin 固件文件。

常用命令参数

在使用 QMK CLI 进行编译时，常用的参数包括：

• -kb 或 --keyboard：指定要编译的键盘名称（如 planck/rev6、ergodox_ez）。
• -km 或 --keymap：指定要编译的键位映射名称（如 default、my_custom_map）。

Docker 部署示例

使用 Docker Run 编译固件

以下命令演示如何使用该镜像编译 Planck 键盘的默认固件：

bash
docker run --rm -it \
  -v $(pwd):/qmk_firmware \
  -w /qmk_firmware \
  qmkfm/qmk_cli \
  qmk compile -kb planck/rev6 -km default

使用 Docker Compose 配置开发环境

如果您需要频繁进行固件开发，可以使用 docker-compose.yml 来简化命令并固化配置：

yaml
version: '3.8'
services:
  qmk-builder:
    image: qmkfm/qmk_cli
    volumes:
      - ./:/qmk_firmware
    working_dir: /qmk_firmware
    command: qmk compile -kb ergodox_ez -km default
    environment:
      - TERM=xterm

启动编译任务：

bash
docker-compose run --rm qmk-builder

相关资源与维护信息

• 官方文档：docs.qmk.fm（支持离线查看与社区 PR 贡献）
• 官方网站：qmk.fm
• 源码仓库：https://github.com/qmk/qmk_firmware
• 社区交流：*** 频道
• 核心维护团队：由 OLKB 的 Jack Humbert 主导，Ergodox EZ 由 ZSA Technology Labs 维护，Clueboard 由 Zach White 维护，Atreus 由 Phil Hagelberg 维护，并拥有庞大的社区贡献者群体。