QMK Firmware External Userspace不 Fork 固件仓库独立维护并自动构建你的键盘键位【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareExternal Userspace 是 QMK Firmware 提供的一项机制把个人键位keymap从 QMK 主仓库中剥离出来存放在一个独立的用户仓库里用qmk config user.overlay_dir指向它之后qmk compile、qmk userspace-add、qmk userspace-compile等命令就能直接识别并构建这些外部键位还可以借助 GitHub Actions 在每次 push 时自动编译并发布固件。读完本篇你可以完成从 External Userspace 仓库搭建、键位添加、构建目标注册到批量编译与 CI 自动化的完整流程并了解底层检测与qmk.json版本校验的源码实现。提示External Userspace 是较新的功能可能还存在一些问题与qmk命令的整合会随版本不断完善。旧版基于 keymap.json 与 GitHub Actions 的构建说明见 旧构建工作流文档本文档已取代其指导地位但旧方式仍应能正常工作。一、核心概念键位可以存放在哪里External Userspace 仓库镜像了主 QMK Firmware 仓库的结构但只包含你希望构建的键位。结合 官方文档 与仓库结构键位共有三种存放方式存放方式路径约定适用场景键盘目录方式keyboards/keyboard/keymaps/keymap/与主仓库一致的组织形式最常用布局目录方式layouts/layout name/keymap name/或layouts/layout/keymap/keymap.*与主仓库的布局系统一致layout name须对应 QMK 中已存在的布局如tkl_ansi传统 userspace 方式users/keymap/兼容 QMK 传统 userspace 特性在 External Userspace 目录内使用相同位置其中users/keymap/即 QMK 传统的用户空间从 users/readme.md 可以看到它是“用户存放可跨键盘复用的代码的地方”构建键位mine时会包含/users/mine/rules.mk并把/users/mine/加入编译搜索路径。External Userspace 让这套机制在仓库之外同样生效。二、设置本地 QMK 环境一次性若要在本地构建需要先在本机设置好 QMK这是一次性过程参见 QMK 新手设置指南。原文档给出两条重要约束若使用与 External Userspace 相关的 QMK CLI 命令如qmk userspace-add当前还需要一份 QMK Firmware 仓库副本本地构建的反馈时间远短于等待 GitHub Actions 完成调试阶段建议优先本地编译。三、创建 External Userspace 仓库GitHub Fork 或纯本地方式 AFork 官方骨架仓库到 GitHub推荐官方提供了一个基础骨架仓库qmk/qmk_userspace若希望把键位托管在 GitHub 上官方强烈建议可以 fork 该仓库作为基础fork 后代码会复制到你的账号下此时将它克隆到本地并开始添加键位cd $HOME git clone https://github.com/{myusername}/qmk_userspace.git qmk config user.overlay_dir$(realpath qmk_userspace)关键点在最后一行qmk config user.overlay_dir...把 CLI 的 overlay 目录指向你的 External Userspace 路径。方式 B仅本地保存如果不想使用 GitHub、希望一切保持在本地直接克隆官方默认 External Userspace 副本cd $HOME git clone https://github.com/qmk/qmk_userspace.git qmk config user.overlay_dir$(realpath qmk_userspace)源码印证overlay 目录是如何被发现的user.overlay_dir只是三种发现机制之一。从 qmk_userspace_paths() 可以看到完整的优先级逻辑当前工作目录向上搜索若ORIG_CWD环境变量存在从该目录逐级向上查找包含qmk.json的目录即“如果你正处在一个含 qmk.json 且带 keyboards/layouts 目录的目录里就把它当作 userspace”QMK_USERSPACE环境变量指向一个存在的目录则加入候选cli.config.user.overlay_dir即上文qmk config user.overlay_dir配置的值会经expanduser().resolve()处理后加入候选。候选列表去重后按顺序保留随后 detect_qmk_userspace() 取第一个能通过qmk.json校验的目录作为最终 userspaceconstants.py 中QMK_USERSPACE与HAS_QMK_USERSPACE就是这一检测结果的全局常量——这也是userspace-add/userspace-compile在定位失败时会提示“运行qmk doctor或qmk userspace-doctor诊断”的原因。四、添加键位以下操作假设你已完成本地 QMK 设置且机器上有一份 QMK Firmware 仓库。External Userspace 中的键位定义方式与主 QMK 仓库完全相同两条创建路径任选其一使用qmk new-keymap命令新建键位或在keyboards目录下手工创建新目录。也可以选择layouts目录存放此时文件路径应为layouts/layout name/keymap name/keymap.*其中layout name必须匹配 QMK 中已存在的布局例如tkl_ansi。创建后构建方式与常规 QMK 用法一致qmk compile -kb keyboard -km keymap警告只有克隆 External Userspace 仓库时执行过qmk config user.overlay_dir...上述构建才能正确找到你的外部键位。五、注册构建目标qmk userspace-add与qmk.json若希望用 GitHub Actions 自动构建固件需要先按键位加入 External Userspace 构建目标命令为qmk userspace-add# 针对键盘/键位组合 qmk userspace-add -kb keyboard -km keymap # 或者针对“松散”存放的 json 键位 qmk userspace-add relative/path/to/my/keymap.json该命令会更新 External Userspace 根目录下的qmk.json。如果你的键位放在 git 仓库里此时是提交并 push 到个人 fork 的好时机。qmk.json的格式与版本源码细节从 UserspaceDefs 的实现可以看到qmk.json的约束文件必须至少包含userspace_version字段按 schemaqmk.user_repo.v0校验之后会按从新到旧顺序尝试qmk.user_repo.v1_1、qmk.user_repo.v1两套 schemav1的build_targets支持两种条目双元素数组[keyboard, keymap]对应qmk userspace-add -kb ... -km ...的形态字符串形式的相对路径指向一个存在的.json键位文件即“松散” json 键位v1.1在此基础上扩展了三元素数组[keyboard, keymap, {env: ...}]为构建附加环境变量。save() 写入时会固定输出userspace_version: 1.1先按最新 schema 自检且仅在内容有变化时才落盘因此重复执行qmk userspace-add不会产生无意义的文件改动。再看 userspace_add 命令实现有两个实用细节位置参数也支持keyboard:keymap形式以及多个构建目标一次传入-kb/-km与位置参数二选一若通过-kb/-km指定的键位尚不存在命令会内部调用new-keymap逻辑先创建该键位再注册构建目标——即“注册即创建”两条路径都支持-e/--env KEYVALUE可多次传入写入 v1.1 的第三项 env 字典用于为单个构建目标附加 make 变量。六、批量编译qmk userspace-compile构建目标就绪后一条命令即可编译全部目标qmk userspace-compile所有登记在 External Userspace 构建目标中的固件都会被构建产物固件文件放在External Userspace 目录的根目录下。从 userspace_compile 实现 可以看到完整参数集参数含义-t/--no-temp构建期间删除临时文件-j/--parallel N并行 make 作业数0表示不限制-c/--clean编译前清理目标文件-n/--dry-run不实际构建仅打印将要执行的命令-p/--print-failures打印失败的构建-e/--env VARVALUE向 make 传递变量可多次传入实现上它把qmk.json中Path型条目包装为JsonKeymapBuildTarget把{keyboard, keymap, env?}型条目交给search_keymap_targets解析最终汇入mass_compile_targets统一执行——这与qmk mass-compile走的是同一条批量编译管线。七、GitHub Actions 自动构建配置好构建目标后利用 GitHub Actions 实现“push 即编译”非常简单在 GitHub 仓库设置中启用 workflowsActions。此后任意一次 push 都会触发所有已配置构建目标的编译完成后 GitHub 上会自动创建一个新 release包含最新编译出的固件文件你可以直接下载并烧录到键盘。这样就形成了完整闭环本地用qmk compile -kb ... -km ...快速验证 →qmk userspace-add注册目标 → commit/push → GitHub Actions 出包 → 从 release 下载固件烧录。八、排错与延伸阅读定位不到 userspace 时userspace-add/userspace-compile报错运行qmk doctor或qmk userspace-doctor诊断常见原因是未执行qmk config user.overlay_dir...或目录中缺少合法qmk.json校验失败UserspaceValidationError会聚合各 schema 版本的错误信息逐条列出可对照 userspace.py 中UserspaceValidationError的实现理解报错结构背景文档External Userspace 官方文档、传统 userspace 特性说明、新手设置指南、旧版构建工作流。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK Firmware External Userspace：不 Fork 固件仓库，独立维护并自动构建你的键盘键位
QMK Firmware External Userspace不 Fork 固件仓库独立维护并自动构建你的键盘键位【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareExternal Userspace 是 QMK Firmware 提供的一项机制把个人键位keymap从 QMK 主仓库中剥离出来存放在一个独立的用户仓库里用qmk config user.overlay_dir指向它之后qmk compile、qmk userspace-add、qmk userspace-compile等命令就能直接识别并构建这些外部键位还可以借助 GitHub Actions 在每次 push 时自动编译并发布固件。读完本篇你可以完成从 External Userspace 仓库搭建、键位添加、构建目标注册到批量编译与 CI 自动化的完整流程并了解底层检测与qmk.json版本校验的源码实现。提示External Userspace 是较新的功能可能还存在一些问题与qmk命令的整合会随版本不断完善。旧版基于 keymap.json 与 GitHub Actions 的构建说明见 旧构建工作流文档本文档已取代其指导地位但旧方式仍应能正常工作。一、核心概念键位可以存放在哪里External Userspace 仓库镜像了主 QMK Firmware 仓库的结构但只包含你希望构建的键位。结合 官方文档 与仓库结构键位共有三种存放方式存放方式路径约定适用场景键盘目录方式keyboards/keyboard/keymaps/keymap/与主仓库一致的组织形式最常用布局目录方式layouts/layout name/keymap name/或layouts/layout/keymap/keymap.*与主仓库的布局系统一致layout name须对应 QMK 中已存在的布局如tkl_ansi传统 userspace 方式users/keymap/兼容 QMK 传统 userspace 特性在 External Userspace 目录内使用相同位置其中users/keymap/即 QMK 传统的用户空间从 users/readme.md 可以看到它是“用户存放可跨键盘复用的代码的地方”构建键位mine时会包含/users/mine/rules.mk并把/users/mine/加入编译搜索路径。External Userspace 让这套机制在仓库之外同样生效。二、设置本地 QMK 环境一次性若要在本地构建需要先在本机设置好 QMK这是一次性过程参见 QMK 新手设置指南。原文档给出两条重要约束若使用与 External Userspace 相关的 QMK CLI 命令如qmk userspace-add当前还需要一份 QMK Firmware 仓库副本本地构建的反馈时间远短于等待 GitHub Actions 完成调试阶段建议优先本地编译。三、创建 External Userspace 仓库GitHub Fork 或纯本地方式 AFork 官方骨架仓库到 GitHub推荐官方提供了一个基础骨架仓库qmk/qmk_userspace若希望把键位托管在 GitHub 上官方强烈建议可以 fork 该仓库作为基础fork 后代码会复制到你的账号下此时将它克隆到本地并开始添加键位cd $HOME git clone https://github.com/{myusername}/qmk_userspace.git qmk config user.overlay_dir$(realpath qmk_userspace)关键点在最后一行qmk config user.overlay_dir...把 CLI 的 overlay 目录指向你的 External Userspace 路径。方式 B仅本地保存如果不想使用 GitHub、希望一切保持在本地直接克隆官方默认 External Userspace 副本cd $HOME git clone https://github.com/qmk/qmk_userspace.git qmk config user.overlay_dir$(realpath qmk_userspace)源码印证overlay 目录是如何被发现的user.overlay_dir只是三种发现机制之一。从 qmk_userspace_paths() 可以看到完整的优先级逻辑当前工作目录向上搜索若ORIG_CWD环境变量存在从该目录逐级向上查找包含qmk.json的目录即“如果你正处在一个含 qmk.json 且带 keyboards/layouts 目录的目录里就把它当作 userspace”QMK_USERSPACE环境变量指向一个存在的目录则加入候选cli.config.user.overlay_dir即上文qmk config user.overlay_dir配置的值会经expanduser().resolve()处理后加入候选。候选列表去重后按顺序保留随后 detect_qmk_userspace() 取第一个能通过qmk.json校验的目录作为最终 userspaceconstants.py 中QMK_USERSPACE与HAS_QMK_USERSPACE就是这一检测结果的全局常量——这也是userspace-add/userspace-compile在定位失败时会提示“运行qmk doctor或qmk userspace-doctor诊断”的原因。四、添加键位以下操作假设你已完成本地 QMK 设置且机器上有一份 QMK Firmware 仓库。External Userspace 中的键位定义方式与主 QMK 仓库完全相同两条创建路径任选其一使用qmk new-keymap命令新建键位或在keyboards目录下手工创建新目录。也可以选择layouts目录存放此时文件路径应为layouts/layout name/keymap name/keymap.*其中layout name必须匹配 QMK 中已存在的布局例如tkl_ansi。创建后构建方式与常规 QMK 用法一致qmk compile -kb keyboard -km keymap警告只有克隆 External Userspace 仓库时执行过qmk config user.overlay_dir...上述构建才能正确找到你的外部键位。五、注册构建目标qmk userspace-add与qmk.json若希望用 GitHub Actions 自动构建固件需要先按键位加入 External Userspace 构建目标命令为qmk userspace-add# 针对键盘/键位组合 qmk userspace-add -kb keyboard -km keymap # 或者针对“松散”存放的 json 键位 qmk userspace-add relative/path/to/my/keymap.json该命令会更新 External Userspace 根目录下的qmk.json。如果你的键位放在 git 仓库里此时是提交并 push 到个人 fork 的好时机。qmk.json的格式与版本源码细节从 UserspaceDefs 的实现可以看到qmk.json的约束文件必须至少包含userspace_version字段按 schemaqmk.user_repo.v0校验之后会按从新到旧顺序尝试qmk.user_repo.v1_1、qmk.user_repo.v1两套 schemav1的build_targets支持两种条目双元素数组[keyboard, keymap]对应qmk userspace-add -kb ... -km ...的形态字符串形式的相对路径指向一个存在的.json键位文件即“松散” json 键位v1.1在此基础上扩展了三元素数组[keyboard, keymap, {env: ...}]为构建附加环境变量。save() 写入时会固定输出userspace_version: 1.1先按最新 schema 自检且仅在内容有变化时才落盘因此重复执行qmk userspace-add不会产生无意义的文件改动。再看 userspace_add 命令实现有两个实用细节位置参数也支持keyboard:keymap形式以及多个构建目标一次传入-kb/-km与位置参数二选一若通过-kb/-km指定的键位尚不存在命令会内部调用new-keymap逻辑先创建该键位再注册构建目标——即“注册即创建”两条路径都支持-e/--env KEYVALUE可多次传入写入 v1.1 的第三项 env 字典用于为单个构建目标附加 make 变量。六、批量编译qmk userspace-compile构建目标就绪后一条命令即可编译全部目标qmk userspace-compile所有登记在 External Userspace 构建目标中的固件都会被构建产物固件文件放在External Userspace 目录的根目录下。从 userspace_compile 实现 可以看到完整参数集参数含义-t/--no-temp构建期间删除临时文件-j/--parallel N并行 make 作业数0表示不限制-c/--clean编译前清理目标文件-n/--dry-run不实际构建仅打印将要执行的命令-p/--print-failures打印失败的构建-e/--env VARVALUE向 make 传递变量可多次传入实现上它把qmk.json中Path型条目包装为JsonKeymapBuildTarget把{keyboard, keymap, env?}型条目交给search_keymap_targets解析最终汇入mass_compile_targets统一执行——这与qmk mass-compile走的是同一条批量编译管线。七、GitHub Actions 自动构建配置好构建目标后利用 GitHub Actions 实现“push 即编译”非常简单在 GitHub 仓库设置中启用 workflowsActions。此后任意一次 push 都会触发所有已配置构建目标的编译完成后 GitHub 上会自动创建一个新 release包含最新编译出的固件文件你可以直接下载并烧录到键盘。这样就形成了完整闭环本地用qmk compile -kb ... -km ...快速验证 →qmk userspace-add注册目标 → commit/push → GitHub Actions 出包 → 从 release 下载固件烧录。八、排错与延伸阅读定位不到 userspace 时userspace-add/userspace-compile报错运行qmk doctor或qmk userspace-doctor诊断常见原因是未执行qmk config user.overlay_dir...或目录中缺少合法qmk.json校验失败UserspaceValidationError会聚合各 schema 版本的错误信息逐条列出可对照 userspace.py 中UserspaceValidationError的实现理解报错结构背景文档External Userspace 官方文档、传统 userspace 特性说明、新手设置指南、旧版构建工作流。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考