更换电脑运行报错问题解决

运行报错解决

GitHub mkdocs serve zsh: command not found: mkdocs ➜ GitHub pip install mkdocs zsh: command not found: pip ➜ GitHub pip3 install mkdocs Defaulting to user installation because normal site-packages is not writeable Collecting mkdocs Downloading mkdocs-1.6.1-py3-none-any.whl (3.9 MB)

你遇到的问题可以总结为一句话：

虽然你已经安装了 mkdocs，但终端还是提示 command not found: mkdocs，因为它的安装路径没有添加到你的系统 PATH 中。

---

背景解释

你运行：

pip3 install mkdocs

虽然安装成功，但你看到这些警告：

WARNING: The script mkdocs is installed in '/Users/wangyongjie/Library/Python/3.9/bin' which is not on PATH.

意思是：mkdocs 脚本被安装到了 ~/Library/Python/3.9/bin 这个目录，但你的终端（zsh）并不知道这个目录里有命令，因此你无法运行 mkdocs。

---

解决方法

✅ 方案 1：临时运行（验证安装成功）

/Users/wangyongjie/Library/Python/3.9/bin/mkdocs serve

如果这样可以运行，说明你确实已经成功安装，只是没配置 PATH。

---

✅ 方案 2：永久解决（推荐）

把安装路径加入到你的 PATH 环境变量中：

1. 打开你的终端配置文件（通常是 ~/.zshrc）：

nano ~/.zshrc

1. 在文件末尾加上这一行：

export PATH="$HOME/Library/Python/3.9/bin:$PATH"

1. 保存并关闭，然后执行：

source ~/.zshrc

1. 再次尝试：

mkdocs serve

---

🔁 补充建议

• 你也可以升级 pip：

/Library/Developer/CommandLineTools/usr/bin/python3 -m pip install --upgrade pip

---

主题报错解决

报错 ➜ wiki_content git:(main) /Users/wangyongjie/Library/Python/3.9/bin/mkdocs serve Error: MkDocs encountered an error parsing the configuration file: while constructing a Python object cannot find module 'material.extensions.emoji' (No module named 'material') in "/Users/wangyongjie/Desktop/代码相关/GitHub/wiki_content/mkdocs.yml", line 85, column 20

这个报错的核心信息是：

❌ MkDocs 无法解析 mkdocs.yml 配置文件中的 material.extensions.emoji，因为你 没有安装 mkdocs-material 主题相关的扩展模块。

---

🔧 原因分析

你的 mkdocs.yml 文件中使用了 Material for MkDocs 的一些扩展功能（如 emoji），这些功能属于 mkdocs-material 插件提供的扩展：

markdown_extensions:
  - material.extensions.emoji

而你目前 只安装了 mkdocs 本体，没有安装 mkdocs-material，所以报错找不到模块。

---

✅ 解决方案

安装 mkdocs-material：

pip3 install mkdocs-material

如果你是局部安装（比如之前 mkdocs 是安装到 ~/Library/... 路径），那你可能也需要使用：

python3 -m pip install --user mkdocs-material

确保和你安装 mkdocs 的方式一致。

---

🌟 验证是否成功

装完之后，再次运行：

/Users/wangyongjie/Library/Python/3.9/bin/mkdocs serve

或者（如果你配置好 PATH）：

mkdocs serve

---

✅ 补充建议（推荐）

如果你不确定配置缺什么，可以在项目根目录下运行：

mkdocs build

它也会告诉你具体缺少哪个模块，方便你补装。

---

如你需要使用更多 Material 主题功能（比如搜索、本地搜索、代码块高亮等），可以参考官方文档：

📚 https://squidfunk.github.io/mkdocs-material/getting-started/

---