105 lines
4.5 KiB
Markdown
105 lines
4.5 KiB
Markdown
# 专治各类疑难杂症
|
||
|
||
## Gitea 提示“找不到对应签名的密钥”
|
||
|
||
仅仅将 SSH 密钥添加到 Gitea 还不够，为了防止他人伪造你的公钥，Gitea 要求你手动验证该密钥的所有权。
|
||
|
||
在你的 SSH / GPG 密钥 列表中，找到刚添加的密钥，点击旁边的验证按钮。
|
||
|
||
Gitea 会弹出一个带有随机 Token 的提示框，并要求你执行一条类似如下的命令：
|
||
|
||
``` bash
|
||
echo -n 'gitea-xxxxxxxxxx' | ssh-keygen -Y sign -n gitea -f /path_to_your_privkey
|
||
```
|
||
|
||
!!! warning "Windows 11 用户避坑警告"
|
||
|
||
千万不要在 Windows 默认的 CMD 或 PowerShell 中执行这段命令！
|
||
|
||
Windows 的 echo 命令不支持 `-n` 参数，它会把 `-n` 甚至回车换行符一起发送给硬件密钥进行签名。这会导致生成的签名数据完全错乱，提交到 Gitea 时会永远报错“签名不匹配”。
|
||
|
||
正确操作是在 Windows 11 中打开 Git Bash。
|
||
|
||
复制 Gitea 提供的命令并在 Git Bash 中执行。将 `/path_to_your_privkey` 替换为你本地密钥路径。(如果读取私钥存根失败，对于硬件密钥也可以尝试指向公钥)
|
||
|
||
终端会输出一段被 `-----BEGIN SSH SIGNATURE-----` 和 `-----END SSH SIGNATURE-----` 包裹的签名块。
|
||
|
||
将这整段签名块复制，粘贴回 Gitea 的网页验证框中，点击确认即可。
|
||
|
||
## Material for MkDocs 粗体无法正常渲染
|
||
|
||
在 Material for MkDocs 中，出现**粗体**无法正常渲染的问题，通常是因为 Markdown 解析器依赖空格或特定的英文单词边界来识别强调语法的起止。
|
||
|
||
当 `**` 直接与中文字符紧凑相连，或紧贴括号、冒号等标点符号时，解析器会将其误认为是一段普通文本的内部字符，从而放弃渲染。
|
||
|
||
针对这个问题，可通过开启并配置 betterem 扩展解决。
|
||
|
||
打开项目的 `mkdocs.yml` 配置文件，找到 `markdown_extensions` 节点，添加 `pymdownx.betterem` 并开启全量智能匹配。
|
||
|
||
``` yaml title="mkdocs.yml"
|
||
markdown_extensions:
|
||
- pymdownx.betterem:
|
||
smart_enable: all
|
||
```
|
||
|
||
配置保存后，MkDocs 重新构建，绝大部分中文字母混排和括号内的加粗问题都会自动恢复正常。
|
||
|
||
如果上述方案不能解决问题，可能是 `smart_enable: all` 弄巧成拙。在 `betterem` 扩展的设计中，“智能(Smart)”这个词的实际含义是：“忽略词内强调(mid-word emphasis)”，即强制要求强调符号 `**` 前后必须有英文空格或单词边界。由于中文汉字之间没有空格，在解析器看来，整句中文是一个连贯的“长单词”。如果设置了 `smart_enable: all`，解析器会把 `**` 也变成“智能”模式，认为它插在“词内”，从而彻底拒绝渲染相连的中文加粗。
|
||
|
||
解决方案是将 `**` 恢复为“非智能（允许词内强调）”模式。关闭全量智能模式，只保留对下划线 `_` 的智能限制（这是官方默认且最适合中文混合排版的设置）。
|
||
|
||
``` yaml title="mkdocs.yml"
|
||
markdown_extensions:
|
||
- pymdownx.betterem:
|
||
smart_enable: '_'
|
||
```
|
||
|
||
## Git 覆盖本地修改
|
||
|
||
!!! warning "注意！"
|
||
|
||
以下命令将使你放弃所有本地更改，而使用远程分支中的副本重置/覆盖所有内容。
|
||
|
||
输入以下命令来覆盖本地文件：
|
||
|
||
``` bash
|
||
git fetch --all
|
||
git reset --hard <remote>/<branch_name>
|
||
```
|
||
|
||
例如：
|
||
|
||
``` bash
|
||
git fetch --all
|
||
git reset --hard origin/main
|
||
```
|
||
!!! info
|
||
|
||
不论是否使用 --hard 选项，所有尚未推送的本地提交都将丢失。
|
||
|
||
### 命令详解
|
||
|
||
`git fetch` 从远程下载最新版本，不会尝试合并或重新设置任何内容。
|
||
|
||
然后 `git reset` 将 main 分支重置为你刚获取的分支。--hard 选项更改工作树中的所有文件，以匹配 origin/main 中的文件。
|
||
|
||
## 擦除 ESP32-S3 固件
|
||
|
||
下载并安装 [esptool](https://github.com/espressif/esptool/releases/latest)
|
||
|
||
令 ESP32-S3 进入 DFU 模式:
|
||
|
||
- 按住板子上的 `BOOT` 按钮不放，将设备接入电脑
|
||
- 再单击一下 `RESET` 按钮
|
||
- 松开 BOOT 按钮
|
||
- 此时电脑会重新识别到一个串口设备
|
||
- 转至 设备管理器
|
||
- 确定 ESP32-S3 设备所对应的串口
|
||
|
||
用命令行工具 esptool 擦除 ESP32-S3 固件，在终端中执行以下命令:
|
||
|
||
``` powershell
|
||
D:\esptool-v5.2.0-windows-amd64\esptool.exe --chip esp32s3 --port [ESP32-S3 设备所对应的串口 e.g.:COM3] erase_flash
|
||
```
|
||
|
||
显示 `Flash memory erased successfully` 后，你就可以像对待一块全新的 ESP32-S3 一样，用常规方法刷写任何其他固件了。 |