aboutsummaryrefslogtreecommitdiff
path: root/docs/zh-cn/newbs_getting_started.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/zh-cn/newbs_getting_started.md')
-rw-r--r--docs/zh-cn/newbs_getting_started.md210
1 files changed, 158 insertions, 52 deletions
diff --git a/docs/zh-cn/newbs_getting_started.md b/docs/zh-cn/newbs_getting_started.md
index 596ab78f7..7ca9871aa 100644
--- a/docs/zh-cn/newbs_getting_started.md
+++ b/docs/zh-cn/newbs_getting_started.md
@@ -1,93 +1,183 @@
1# 介 1# 置环境
2 2
3你的电脑键盘里面包含一个处理器, 这个处理器和你电脑里面的不太一样。这个处理器负责运行一些特殊的软件，这些软件可以监测按钮按下并将按钮处于按下还是释放状态的数据发送出去。QMK就是这样一种软件，即监测按钮被按下并发送这样的信息到作为主机的计算机上。当你创建了你的布局, 你也就创建了你的键盘运行的的可执行程序。 3<!---
4 original document: 0.15.12:docs/newbs_getting_started.md
5 git diff 0.15.12 HEAD -- docs/newbs_getting_started.md | cat
6-->
4 7
5QMK试图通过使简单的事情变得更简单，使使不可能成为可能来把大量的权力交给你。你不需要懂如何通过程序创建强大的布局——你只需要遵循简单的语法规则。 8构建键映射前，有一些必须安装配置的构建工具，但无论你要编译多少个固件，这一步只需要做一次。
6 9
7# 新手上 10## 1. 必备具
8 11
9在你能创建布局前,你要安装一些软件来建立你的开发环境。无论你想编译多少固件，这个操作都只需要进行一次。 12首先需要确保一些基本的软件配备。
10 13
11如果您更喜欢图形化界面, 请考虑使用在线工具[QMK配置器](https://config.qmk.fm)。 请参考 [使用在线GUI构建您的第一个固件](newbs_building_firmware_configurator.md)。 14* [文本编辑器](zh-cn/newbs_learn_more_resources.md#text-editor-resources)
15 * 你需要至少一个能编辑常规文本的软件。系统自带的编辑器通常不会如实保存（会做一些额外的处理，如回车），所以选择编辑器时需要留意。
16* [QMK工具箱(可选)](https://github.com/qmk/qmk_toolbox)
17 * 在Windows及macOS上可用的图形程序，用于编辑及调试你的键盘
12 18
19?> 如果你没有Linux/Unix命令行使用经验，有些基本概念需要先学习一下。[这些资料](zh-cn/newbs_learn_more_resources.md#command-line-resources)是个使用QMK很好的参考。
13 20
14## 下载软 21## 2. 准备构环境 :id=set-up-your-environment
15 22
16### 23已尽力让QMK易于配置了你只备好Linux或Unix环境，剩的交给QMK来安装。
17 24
18你需要一个可以编辑 **纯文本** 文件的程序。在Windows上你可以用Notepad, 在Linux上使用gedit，这两个都是简单又实用的文本编辑工具。 在macOS上, 请小心使用 “文本编辑” 这个默认软件: 如果你不明确的选择_格式_菜单中的 _制作纯文本_ 的话文本将不会被保存为纯文本。 25<!-- tabs:start -->
19 26
20你也可以下载并安装一个专用编辑器 [Sublime Text](https://www.sublimetext.com/) 或 [VS Code](https://code.visualstudio.com/)。 这大概是跨平台的最好方法了, 这些编辑器是专门为了编辑代码设计的。 27### ** Windows **
21 28
22?>搞不清用哪种编辑器? Laurence Bradford 写了篇关于编辑器选择的文章 [a great introduction](https://learntocodewith.me/programming/basics/text-editors/)。 29QMK有维护一套基于MSYS2的软件包，所有命令行程序和依赖都是齐备的。通过 `QMK MSYS` 快捷命令可以快速启动开发环境。
23 30
24### QMK 工具箱 31#### 依赖项
25 32
26QMK 工具箱 是一种可选的Windows和macOS下的图形化工具，它可以对你的定制键盘进行编程和调试。你可能会发现它就是你能简单的刷新你的键盘固件并查看调试信息的稀世珍宝。 33需安装[QMK MSYS](https://msys.qmk.fm/)，最新版在[这里](https://github.com/qmk/qmk_distro_msys/releases/latest)。
27 34
28[下载最新](https://github.com/qmk/qmk_toolbox/releases/latest) 35此，如想安装MSYS2环境，下面给了体骤。
29 36
30* Windows用户: `qmk_toolbox.exe` (绿色版) 或 `qmk_toolbox_install.exe` (安装版) 37<details>
31* macOS用户: `QMK.Toolbox.app.zip` (绿色版) or `QMK.Toolbox.pkg` (安装版) 38 <summary>自行安装</summary>
32 39
33## 建境 40?> 决定 `QMK MSYS`，跳过此节.
34 41
35我们为了使QMK环境变得更容易建立已竭尽所能。你只需要准备Linux 或 Unix 环境, 然后让QMK安装剩余部分。 42#### 依赖项
36 43
37?> 如果你从未使用过Linux/Unix的命令行,有一些你需要学习的基础概念和命令，以下资料将教会您使用QMK环境的必要能力:<br> 44遵循 https://www.msys2.org 上的指引，安装MSYS2、Git和Python。
38[必会Linux命令](https://www.guru99.com/must-know-linux-commands.html)<br>
39[一些基本的Unix命令](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
40 45
41### Windows 46在MSYS2安装完毕后，关闭所有的MSYS终端，启动新的MinGW 64-bit终端。
42 47
43你需要安装MSYS2和Git. 48!> **注意:** MinGW 64-bit 终端*不同于*安装包最后打开的MSYS终端，窗口标题应当是紫色的"MINGW64"而不是"MSYS"。具体的差异可以[参考这里](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems)。
44 49
45* 按照以下安装说明进行操作[MSYS2 主页](https://www.msys2.org)。 50执行如下命令：
46* 关闭所有打开的MSYS2终端并打开新的MSYS2 MinGW 64-bit终端。
47* 使用以下命令安装Git: `pacman -S git`。
48 51
49### macOS 52 pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip
50 53
51你需要安装Homebrew。按照以下说明进行操作 [Homebrew 主页](https://brew.sh)。 54#### 安装
52 55
53Homebrew装完成后, 继续 _同步QMK程_. 这一步将通运一个脚本装其他包。 56安装QMK行程:
54 57
55### Linux 58 python3 -m pip install qmk
56 59
57你将需要安装Git.你很有可能已经安装,但若你尚未安装,可以使用以下命令进行安装: 60</details>
58 61
59* Debian / Ubuntu / Devuan: `apt-get install git` 62### ** macOS **
60* Fedora / Red Hat / CentOS: `yum install git`
61* Arch: `pacman -S git`
62 63
63?> 无论你使用哪种平台，Docker都可以是你的选择[点这里进一步了解](getting_started_build_tools.md#docker) 64QMK维护了一套Homebrew tap和formula以用于自动安装命令行程序及依赖项。
64 65
65## 同步QMK工程 66#### 依赖项
66 67
67当你建立Linux/Unix环境后,你就已经可以下载QMK了.下载时我们可以用Git来 "clone" QMK仓库. 打开一个终端或MSYS2 MinGW 窗口，在阅读剩余的指南时请保持窗口打开。在窗口里面运行以下两句命令: 68须先安装Homebrew，可以参考 https://brew.sh
68 69
69```shell 70#### 安装
70git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git 71
71cd qmk_firmware 72安装QMK命令行程序：
72``` 73
74 brew install qmk/qmk/qmk
75
76### ** Linux/WSL **
77
78?> **WSL用户注意**: 默认情况下，QMK仓库会被clone到home目录下，如果想指定其它目录，务必留意要放在WSL文件系统中（即，非 `/mnt` 目录下），否则文件读写会[非常慢](https://github.com/microsoft/WSL/issues/4197).
79
80#### 依赖项
81
82须安装Git及Python，通常你肯定已经有了，如果确实没有，请使用下面的方法尝试安装：
83
84* Debian / Ubuntu / Devuan: `sudo apt install -y git python3-pip`
85* Fedora / Red Hat / CentOS: `sudo yum -y install git python3-pip`
86* Arch / Manjaro: `sudo pacman --needed --noconfirm -S git python-pip libffi`
87* Void: `sudo xbps-install -y git python3-pip`
88* Solus: `sudo eopkg -y install git python3`
89* Sabayon: `sudo equo install dev-vcs/git dev-python/pip`
90* Gentoo: `sudo emerge dev-vcs/git dev-python/pip`
91
92#### 安装
93
94安装QMK命令行程序：
95
96 python3 -m pip install --user qmk
97
98#### 社区提供的包
99
100有一些社区成员提供的包，可能版本会有落后或是功能不全的问题，如果你遇到了什么问题，请联系维护它的社区成员。
101
102Arch系环境下可以使用官方源安装命令行程序（在写这份文档时，有些依赖项被标记为可选的，其实不是）：
103
104 sudo pacman -S qmk
105
106也可以尝试AUR的 `qmk-git`：
107
108 yay -S qmk-git
109
110### ** FreeBSD **
111
112#### 安装
113
114使用FreeBSD包安装QMK命令行程序：
115
116 pkg install -g "py*-qmk"
117
118请遵循安装后输出的指引操作进行配置（使用 `pkg info -Dg "py*-qmk"` 可以显示这份指引）。
119
120<!-- tabs:end -->
121
122## 3. 执行QMK配置 :id=set-up-qmk
123*译注：由于setup过程中需要从github clone依赖项，请先确保科学上网*
124
125<!-- tabs:start -->
73 126
74?> 如果您已经知道[如何使用GitHub](getting_started_github.md), 我们推荐您创建您自己的分支并克隆。 如果您不知道这是什么, 您完全可以忽略这句无关紧要的话。 127### ** Windows **
75 128
76QMK附一个脚本，可帮助设置余的所需内容.您可以通输入此命令来运它: 129安装QMK，行：
77 130
78 util/qmk_install.sh 131 qmk setup
79 132
80## 试你的环 133通常有的询问 `y` 行了。
81 134
82现在你的QMK环境已经建立完毕, 你可以为你的键盘创建固件了。开始试着创建键盘的默认固件吧。 你需要使用以下格式的命令创建固件: 135### ** macOS **
83 136
84 make <keyboard>:default 137安装QMK后，执行：
85 138
86比如, 制作一个Clueboard 66%的固件，需要用: 139 qmk setup
87 140
88 make clueboard/66/rev3:default 141通常所有的询问回复 `y` 就行了。
89 142
90当完成后你要看到一些回显，尾部如下: 143### ** Linux/WSL **
144
145安装QMK后，执行：
146
147 qmk setup
148
149通常所有的询问回复 `y` 就行了。
150
151?>**Debian及Ubuntu系环境须留意**:
152也许你会遇到 `bash: qmk: command not found` 错误，主要是因为Debian上的Bash 4.4版本引入的一个[bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155)，`$HOME/.local/bin` 被从PATH环境变量中删除了，后续版本中这个问题已被修复。
153然而Ubuntu很挫地再次引入了这个bug[且没有修复](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562)。
154不过修复也很容易，在当前账户中执行：`echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc`
155
156### ** FreeBSD **
157
158安装QMK后，执行：
159
160 qmk setup
161
162通常所有的询问回复 `y` 就行了。
163
164<!-- tabs:end -->
165
166?> QMK的home目录可以在安装时通过 `qmk setup -H <path>` 来指定，安装后也可以通过[命令行程序来配置](zh-cn/cli_configuration.md?id=single-key-example)`user.qmk_home`变量，可以通过 `qmk setup --help` 查看所有可用配置。
167
168?> 若你熟悉GitHub，[推荐阅读这份指引](zh-cn/getting_started_github.md)通过 `qmk setup <github_username>/qmk_firmware` 来clone你自己的fork。如果你看不懂这一段啥意思，忽略就是了。
169
170## 4. 测试你的构建环境
171
172QMK构建环境搭建完成，可以尝试构建一个键盘固件。使用以下指令格式，先试试编译默认提供的键映射：
173
174 qmk compile -kb <keyboard> -km default
175
176例如，要构建一个Clueboard 66%，就这样执行：
177
178 qmk compile -kb clueboard/66/rev3 -km default
179
180你应当能看到像这样的输出信息：
91 181
92``` 182```
93Linking: .build/clueboard_66_rev3_default.elf [OK] 183Linking: .build/clueboard_66_rev3_default.elf [OK]
@@ -97,6 +187,22 @@ Checking file size of clueboard_66_rev3_default.hex
97 * The firmware size is fine - 26356/28672 (2316 bytes free) 187 * The firmware size is fine - 26356/28672 (2316 bytes free)
98``` 188```
99 189
100# 创建你的布局 190## 5. 配置你的构建环境 (可选的)
191
192通过对默认配置的简单调整，QMK用起来会更有趣一些，我们来试试！
193
194大部分QMK新手手头只有一把键盘，可以通过 `qmk config` 命令将它设置为默认键盘，例如你想将 `clueboard/66/rev4` 设置为默认，可以这样：
195
196 qmk config user.keyboard=clueboard/66/rev4
197
198也可以调整默认的键映射名称。社区上大家常用自己的GitHub用户名，这也是我们推荐的做法。
199
200 qmk config user.keymap=<github_username>
201
202完成后，这些配置就不用管了，编译键盘固件就可以直接这样执行：
203
204 qmk compile
205
206# 制作你自己的键映射
101 207
102现在你可以创建属于你自己的布局了! 请移步 [构建你的第一个固件](newbs_building_firmware.md)来继续。 208万事俱备啦！请继续阅读[构建第一个固件](zh-cn/newbs_building_firmware.md).
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-15 18:20:39 +0000