第 1 步：安装与配置

在开始之前，请确保你的系统已经安装了 Python，推荐使用 pyenv 来管理不同版本的 Python。

1. Spacemacs Layer 配置

Spacemacs 的核心是 Layer，你需要确保 python layer 已经被启用。

打开你的 Spacemacs 配置文件 ~/.spacemacs，在 dotspacemacs-configuration-layers 列表中添加 python：

dotspacemacs-configuration-layers
  '(
    ;; other layers
    python
    ;; other layers
    )

保存文件后，Spacemacs 会提示你重新加载配置，按 y 确认，它会自动安装所需的依赖包（如 lsp-pyright 或 lsp-jedi，它们是 Python 的语言服务器）。

2. Python 解释器选择

强烈推荐使用 pyenv 来管理 Python 版本，安装 pyenv 后，你可以在项目目录下为项目指定 Python 版本：

# 在项目根目录
pyenv local 3.11.4  # 设置项目使用 Python 3.11.4

当你在 Spacemacs 中打开这个项目时，它会自动检测并使用这个版本的 Python。

如果你不使用 pyenv，Spacemacs 会使用系统默认的 python 或 python3 命令。

第 2 步：基本使用 (LSP + Company)

加载 python layer 后，Spacemacs 会自动启动 LSP 和 Company 模式，提供现代化的 IDE 体验。

1. 检查 LSP 状态

打开一个 .py 文件后，状态栏（Mode Line）的右侧会显示 LSP 的状态，你应该能看到类似 LSP:pyright 或 LSP:jedi 的字样,表示语言服务器已成功连接。

如果没看到，可以手动启动 LSP： SPC l s (lsp-start)

2. 自动补全

当你输入代码时，Company 会自动弹出补全建议,你可以：

• TAB 选择建议项。
• Enter 确认。
• 使用 Ctrl-n / Ctrl-p 在建议列表中导航。

3. 代码检查与错误提示

LSP 会实时分析你的代码，并在左侧的“飞航”上用波浪线标出错误和警告，将光标移到标记上,会显示具体的错误信息。

4. 获取帮助

• 查看函数/变量的文档：将光标放在函数或变量上，按 SPC h d (describe-symbol)。
• 跳转到定义：将光标放在函数/变量上，按 SPC g g (xref-go-to-definition)。
• 返回：跳转后，按 SPC t t (pop-tag-mark) 返回原位置。
• 查找引用：按 SPC g r (xref-find-references)。

第 3 步：运行 Python 代码

这是你最关心的部分，Spacemacs 提供了多种运行代码的方式。

在终端中运行 (最常用)

这是最直接的方式,就像在命令行里一样。

1. 打开你的 Python 文件，hello.py：

   # hello.py
   def greet(name):
       print(f"Hello, {name}!")
   if __name__ == "__main__":
       greet("Spacemacs User")

2. 在 Spacemacs 中，按 SPC ! 打开命令提示符。

3. 输入 python hello.py 并回车。

这会在 Spacemacs 底部弹出的一个 *shell* 缓冲区中执行你的脚本,并输出结果。

快捷键优化：你可以为常用命令创建快捷键，在 ~/.spacemacs 的 dotspacemacs/user-config 部分添加：

(defun run-python-file ()
  "Run the current Python file in a shell."
  (interactive)
  (let ((file-name (buffer-file-name)))
    (if file-name
        (progn
          (split-window-below)
          (other-window 1)
          (shell-command (concat "python " file-name)))
      (message "Not in a file buffer."))))
(spacemacs/set-leader-keys "p r" 'run-python-file)

配置后，你就可以直接按 SPC p r 来运行当前文件了。

使用 run-python 交互式解释器

这会启动一个 Python REPL (Read-Eval-Print Loop) 在 Spacemacs 内部。

1. 按 SPC ' p (run-python)。
2. 这会打开一个 *Python* 缓冲区,也就是一个交互式终端。
3. 你可以在这个缓冲区里直接输入 Python 代码并回车执行。
4. 如果你想在代码文件中执行某段代码，选中代码，然后按 SPC ' s (spacemacs/send-region-to-python)，代码会被发送到 *Python* 缓冲区执行。

使用 EIN (Emacs IPython Notebook)

EIN 提供了类似 Jupyter Notebook 的体验,特别适合数据分析和科学计算。

1. 确保你的 Python 环境安装了 jupyter：

   pip install jupyter

2. 按 SPC SPC (M-x)，然后输入 ein:run 并回车。
3. 这会启动一个 Jupyter 内核，并打开一个 *EIN* 缓冲区,你可以在这里编写和执行代码块。

第 4 步：调试 Python 代码

Spacemacs 集成了强大的 dap-mode (Debug Adapter Protocol)，让你可以像在 VS Code 中一样进行图形化调试。

1. 安装 DAP 依赖： 在你的 Python 环境中安装调试器适配器：

   pip install debugpy

2. 启动调试会话： 打开你的 Python 文件，确保你的代码中有断点（在行号左边点击，或按 SPC b d 设置断点）。 按 SPC d d (dap-debug)。

3. 选择调试配置： 首次使用时，Spacemacs 会提示你选择一个调试配置，选择 Python: File，这会在项目根目录创建一个 .vscode/launch.json 文件,用于存储调试配置。

4. 控制调试： 调试启动后，会打开一个 *DAP-DEBUG-SESSION* 缓冲区，并显示一个工具栏,你可以使用以下快捷键：

   • F5 (dap-continue): 继续执行,直到下一个断点。
   • F10 (dap-next): 单步跳过（不进入函数）。
   • F11 (dap-step-in): 单步进入（进入函数）。
   • F12 (dap-step-out): 单步跳出（从当前函数出来）。
   • SPC d b (dap-breakpoint-toggle): 切换断点。
   • SPC d l (dap-disconnect): 断开调试。

第 5 步：虚拟环境管理

强烈建议为每个项目创建独立的虚拟环境。

手动方式 (推荐)

1. 在项目根目录创建虚拟环境：

   python -m venv .venv

2. 激活虚拟环境：

   source .venv/bin/activate

   在激活后，你的 shell 提示符前会出现 (.venv)。

3. 在 Spacemacs 中使用： 在激活了虚拟环境的 shell 中启动 emacs 或 spacemacs，这样，LSP、run-python 等工具就会自动使用虚拟环境中的 Python 解释器和安装的包。

自动方式 (使用 conda.el)

如果你使用 conda，可以安装 conda layer 并进行配置,可以实现更便捷的环境切换。

总结与常用快捷键

故障排除

• LSP 不工作或报错：

  1. 检查 pyright 或 jedi 是否已安装：pip list | grep pyright。
  2. 检查 Python 解释器路径是否正确。
  3. 尝试重启 LSP: SPC l r (lsp-restart)。
  4. 查看 *lsp-log* 缓冲区获取详细错误信息。

• 自动补全不出现：

  1. 确认 python layer 已加载。
  2. 确认 LSP 已启动。
  3. 检查 *company* 缓冲区是否有错误信息。

希望这份详细的指南能帮助你在 Spacemacs 中高效地使用 Python！