qmkfm/qmk_configurator

QMK Configurator (Quantum Mechanical Keyboard Configurator)

镜像概述

QMK Configurator 是一个基于 Web 的在线工具，专为 https://github.com/qmk/qmk_firmware 支持的机械键盘设计。该镜像封装了 QMK Configurator 的前端运行环境，允许用户通过直观的界面创建、编辑和保存 .json 格式的键映射（Keymap）文件，并自动生成适用于目标键盘的固件文件以便进行刷机。

核心功能和特性

• 可视化键映射编辑：提供图形化界面，轻松配置键盘按键映射、宏命令和层级（Layers）。
• 固件自动生成：根据用户配置的 JSON 键映射文件，自动调用后端 API 编译并生成可刷写的固件文件（如 .hex 或 .bin）。
• 配置导入/导出：支持保存和加载本地 .json 配置文件，方便备份和分享键盘布局。
• 多语言支持：内置国际化（i18n）支持，满足全球不同语言用户的需求。
• 容器化部署：提供开箱即用的 Docker 镜像，内置 Nginx 或相关 Web 服务器，一键启动自包含的运行环境。

使用场景和适用范围

• 客制化键盘玩家：在没有外网访问或希望保护隐私的本地网络环境中，自建 QMK 配置服务。
• 键盘开发者与厂商：在本地开发、测试和调试 QMK 前端界面，或为特定键盘产品提供私有的固件配置门户。
• CI/CD 与自动化测试：在持续集成环境中运行端到端（E2E）测试或单元测试。

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

1. 基础部署

如果您只需要一个默认的本地运行环境，可以直接运行以下命令。该命令会启动一个自包含的 Web 服务，并将容器的 80 端口映射到宿主机的 8080 端口。

bash
docker run -d -p 8080:80 --name qmk-configurator qmkfm/qmk_configurator:latest

启动后，通过浏览器访问 http://localhost:8080 即可使用。

2. 自定义后端 API 地址

默认情况下，前端会请求官方的 QMK API。如果您在本地自建了 QMK 编译后端（API 服务器），可以通过设置 VUE_APP_API_URL 环境变量来指定自定义的后端地址：

bash
docker run -d \
  -e VUE_APP_API_URL=http://localhost:8080 \
  -p 8080:80 \
  --name qmk-configurator \
  qmkfm/qmk_configurator:latest

注意：VUE_APP_API_URL 是在构建时注入的环境变量。如果官方镜像未将其配置为运行时动态读取，您可能需要重新构建镜像以使其生效，具体请参考官方 Vue CLI 环境变量说明。

3. 本地开发模式（挂载本地代码）

如果您需要修改前端代码并进行本地开发，可以将本地项目目录挂载到容器中，实现代码的热重载和实时调试。

bash
docker run -d \
  --mount type=bind,source="$(pwd)",target=/qmk_configurator \
  -p 8080:80 \
  --name qmk-configurator-dev \
  qmkfm/qmk_configurator:latest

注：原文档中使用的 type=volume,source=. 语法在标准 Docker 中适用于命名卷，若需绑定当前宿主机目录，请使用上述 type=bind 语法或简写的 -v $(pwd):/qmk_configurator。

4. 环境变量说明

本地开发与构建指南

如果您选择不使用 Docker，或者需要深入参与项目开发，建议在本地配置 Node.js 环境。推荐使用 https://github.com/nvm-sh/nvm 来管理 Node 版本，项目根目录下的 .nvmrc 文件指定了经过测试的兼容版本。

环境准备与依赖安装

bash
# 切换至项目指定的 Node 版本
nvm use

# 安装项目依赖
yarn install

开发运行与构建

bash
# 启动开发服务器（支持热重载）
yarn run serve

# 编译并压缩代码以用于生产环境
yarn run build

测试与代码检查

bash
# 运行代码规范检查并自动修复
yarn run lint

# 运行单元测试
yarn run test:unit

# 运行端到端 (E2E) 测试 (需单独启动开发服务器)
yarn run test:cypress

# 以 CI 模式运行端到端测试
yarn run test:cypress:ci

构建自定义 Docker 镜像

如果您修改了源码并希望构建自己的 Docker 镜像，请在项目根目录执行以下命令（构建过程可能需要较长时间）：

bash
# 构建镜像
docker build -t qmk_configurator .

# 运行自定义构建的镜像
docker run -d -p 8080:80 qmk_configurator

相关参考

• 项目仓库：https://github.com/qmk/qmk_configurator
• QMK 固件仓库：https://github.com/qmk/qmk_firmware
• 国际化指南：请参考项目仓库中的 internationalization_guide.md 文档。
• Vue CLI 配置参考：Configuration Reference