强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

Emacs 完全指南 / 第 02 章:安装与配置

第 02 章:安装与配置

2.1 安装原版 Emacs

各平台安装方式

Linux

# Ubuntu / Debian(推荐使用 PPA 获取最新版本)
sudo add-apt-repository ppa:kelleyk/emacs
sudo apt update
sudo apt install emacs29    # 或 emacs28

# Fedora
sudo dnf install emacs

# Arch Linux
sudo pacman -S emacs

# NixOS / Nix(推荐的跨平台方式)
nix-env -iA nixpkgs.emacs

# Snap
sudo snap install emacs --classic

# Flatpak
flatpak install flathub org.gnu.emacs

macOS

# Homebrew(推荐)
brew install --cask emacs        # GUI 版本
brew install emacs-plus@29       # 带额外功能的版本

# MacPorts
sudo port install emacs-app +nativecomp

# 直接下载
# 访问 https://emacsformacos.com/ 下载预编译版本

Windows

# Chocolatey
choco install emacs

# Scoop
scoop install emacs

# MSYS2(推荐用于获取最新版本)
pacman -S mingw-w64-x86_64-emacs

# 直接下载
# 访问 https://ftp.gnu.org/gnu/emacs/windows/ 下载

版本选择建议

版本推荐程度说明
Emacs 29+⭐⭐⭐⭐⭐内置 Tree-sitter、use-package
Emacs 28⭐⭐⭐⭐原生编译支持
Emacs 27⭐⭐⭐可用但缺少部分新特性
Emacs 26 及以下⭐⭐不推荐,缺少重要功能

验证安装

# 查看版本
emacs --version
# 输出示例: GNU Emacs 29.4

# 检查原生编译是否启用
emacs --batch --eval '(message "%s" (if (fboundp '\''native-comp-available-p) "native-comp 支持" "无原生编译"))'

# 检查 Tree-sitter 支持
emacs --batch --eval '(message "%s" (if (treesit-available-p) "Tree-sitter 支持" "无 Tree-sitter"))'

提示: 建议安装 Emacs 29 或更高版本,内置了 use-package 和 Tree-sitter 支持, 免去额外配置的麻烦。


2.2 配置目录结构

Emacs 的配置文件位于 ~/.emacs.d/~/.config/emacs/ 目录。

目录结构详解

~/.emacs.d/                     # 传统位置
├── early-init.el               # 最早加载(在 GUI 初始化之前)
├── init.el                     # 主配置入口
├── custom.el                   # Emacs 自动保存的自定义设置
├── lisp/                       # 自定义 Elisp 模块
│   ├── init-ui.el              # 界面设置
│   ├── init-editing.el         # 编辑设置
│   ├── init-completion.el      # 补全系统
│   ├── init-programming.el     # 编程设置
│   └── init-org.el             # Org-mode 设置
├── modules/                    # 自定义功能模块
│   ├── my-utils.el             # 工具函数
│   └── my-keybindings.el       # 键位绑定
├── snippets/                   # Yasnippet 片段
│   ├── python-mode/
│   └── org-mode/
├── themes/                     # 自定义主题
├── elpa/                       # ELPA 包安装目录
├── straight/                   # straight.el 缓存
└── backups/                    # 自动备份文件

加载顺序

Emacs 启动
    │
    ▼
early-init.el          ← 最先加载,用于设置 GUI 和垃圾回收
    │
    ▼
init.el                ← 主配置入口
    │
    ├── (require 'init-ui)
    ├── (require 'init-editing)
    ├── (require 'init-completion)
    ├── (require 'init-programming)
    └── (require 'init-org)
    │
    ▼
Emacs 就绪

early-init.el

;;; early-init.el --- 早期初始化配置 -*- lexical-binding: t; -*-

;; 禁用菜单栏、工具栏、滚动条
(push '(menu-bar-lines . 0) default-frame-alist)
(push '(tool-bar-lines . 0) default-frame-alist)
(push '(vertical-scroll-bars) default-frame-alist)

;; 优化启动速度:提高垃圾回收阈值
(setq gc-cons-threshold most-positive-fixnum)

;; 启动完成后恢复合理的垃圾回收阈值
(add-hook 'emacs-startup-hook
          (lambda ()
            (setq gc-cons-threshold (* 16 1024 1024))))  ; 16MB

;; 禁用 package.el(如果使用 straight.el)
(setq package-enable-at-startup nil)

;; 设置默认字体(避免闪烁)
(add-to-list 'default-frame-alist '(font . "JetBrains Mono-14"))

(provide 'early-init)

init.el

;;; init.el --- 主配置文件 -*- lexical-binding: t; -*-

;; 添加 lisp 目录到 load-path
(add-to-list 'load-path (expand-file-name "lisp" user-emacs-directory))

;; 加载各模块
(require 'init-ui)          ; 界面配置
(require 'init-editing)     ; 编辑配置
(require 'init-completion)  ; 补全系统
(require 'init-programming) ; 编程配置
(require 'init-org)         ; Org-mode

;; 自定义设置保存到单独文件
(setq custom-file (expand-file-name "custom.el" user-emacs-directory))
(when (file-exists-p custom-file)
  (load custom-file))

(provide 'init)

2.3 Doom Emacs 安装与配置

系统依赖

# Ubuntu / Debian
sudo apt install git ripgrep fd-find cmake libtool libtool-bin

# Fedora
sudo dnf install git ripgrep fd cmake libtool

# macOS
brew install git ripgrep fd cmake coreutils

# Arch Linux
sudo pacman -S git ripgrep fd cmake

安装步骤

# 1. 备份旧配置
mv ~/.emacs.d ~/.emacs.d.bak
mv ~/.emacs   ~/.emacs.bak

# 2. 克隆 Doom Emacs
git clone --depth 1 https://github.com/doomemacs/doomemacs ~/.config/emacs

# 3. 运行安装脚本
~/.config/emacs/bin/doom install

# 4. 将 doom 命令加入 PATH
echo 'export PATH="$HOME/.config/emacs/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 5. 验证安装
doom doctor    # 检查环境
doom version   # 查看版本

Doom Emacs 配置文件

~/.config/doom/
├── init.el        # 模块启用/禁用
├── config.el      # 个人配置
└── packages.el    # 额外包声明

init.el — 模块配置

;;; init.el -*- lexical-binding: t; -*-

(doom! :input
       ;; chinese          ; 中文输入法支持
       ;; japanese

       :completion
       (company +childframe)  ; 自动补全
       (vertico +icons)       ; 垂直补全框架

       :ui
       doom                   ; Doom 主题
       doom-dashboard         ; 启动界面
       modeline               ; 状态栏
       ophints                ; 操作提示
       (popup +defaults)      ; 弹窗管理
       ;; treemacs             ; 项目侧边栏
       unicode                ; Unicode 支持
       vc-gutter              ; Git 差异标记
       vi-tilde-fringe        ; 空行标记
       workspaces             ; 工作空间

       :editor
       (evil +everywhere)     ; Vim 模态编辑
       file-templates         ; 文件模板
       fold                   ; 代码折叠
       (format +onsave)       ; 格式化
       snippets               ; 代码片段

       :emacs
       dired                  ; 文件管理
       electric               ; 智能缩进
       undo                   ; 撤销树
       vc                     ; 版本控制

       :term
       vterm                  ; 终端模拟

       :checkers
       syntax                 ; 语法检查
       (spell +flyspell)      ; 拼写检查

       :tools
       (debugger +lsp)        ; 调试
       (docker +lsp)          ; Docker
       (eval +overlay)        ; 代码执行
       lookup                 ; 文档查找
       (lsp +peek)            ; 语言服务器
       magit                  ; Git 客户端
       make                   ; 构建工具
       ;; rgb                   ; 颜色工具

       :lang
       (cc +lsp)              ; C/C++
       emacs-lisp             ; Elisp
       (json +lsp)            ; JSON
       (markdown +grip)       ; Markdown
       (org +roam2)           ; Org-mode + Roam
       (python +lsp +pyright) ; Python
       (rust +lsp)            ; Rust
       (sh +lsp)              ; Shell
       (web +lsp)             ; Web
       (yaml +lsp)            ; YAML

       :config
       (default +bindings +smartparens))

config.el — 个人配置示例

;;; config.el -*- lexical-binding: t; -*-

;; 基本设置
(setq user-full-name "Your Name"
      user-mail-address "your@email.com")

;; 主题
(setq doom-theme 'doom-one)

;; 字体
(setq doom-font (font-spec :family "JetBrains Mono" :size 14)
      doom-variable-pitch-font (font-spec :family "Noto Sans" :size 14)
      doom-unicode-font (font-spec :family "Noto Color Emoji"))

;; 行号
(setq display-line-numbers-type 'relative)

;; Org-mode 配置
(after! org
  (setq org-directory "~/org/"
        org-agenda-files '("~/org/agenda/")
        org-default-notes-file "~/org/inbox.org"))

;; LSP 设置
(after! lsp-mode
  (setq lsp-idle-delay 0.5
        lsp-log-io nil))

packages.el — 额外包

;; -*- no-byte-compile: t; -*-
;;; $DOOMDIR/packages.el

;; 安装额外的包
(package! rainbow-delimiters)
(package! tree-sitter)
(package! tree-sitter-langs)

Doom 常用命令

doom install          # 首次安装
doom sync             # 同步配置(修改 config 后运行)
doom upgrade          # 更新 Doom 和所有包
doom doctor           # 诊断环境问题
doom clean            # 清理未使用的包
doom build            # 重新编译所有包
doom env              # 生成环境变量文件

2.4 Spacemacs 安装与配置

安装步骤

# 1. 备份旧配置
mv ~/.emacs.d ~/.emacs.d.bak

# 2. 克隆 Spacemacs
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d

# 3. 启动 Emacs,Spacemacs 会自动下载依赖
emacs

# 4. 首次启动时选择风格
# - Vim 风格 (推荐)
# - Emacs 风格
# - Hybrid 风格

Spacemacs 配置文件

~/.spacemacs                # 主配置文件
~/.spacemacs.d/             # 配置目录(可选)
├── init.el                 # 用户配置
└── layers/                 # 自定义 layer

Spacemacs Layer 配置

;; ~/.spacemacs 中的 dotspacemacs-configuration-layers

dotspacemacs-configuration-layers
'(
  ;; 编程语言
  (python :variables
          python-backend 'lsp
          python-formatter 'black)
  (javascript :variables
              javascript-backend 'lsp
              javascript-fmt-tool 'prettier)
  (rust :variables rust-backend 'lsp)
  (go :variables go-backend 'lsp)

  ;; 工具
  (lsp :variables
       lsp-ui-doc-enable t
       lsp-ui-sideline-enable t)
  git
  (version-control :variables
                   version-control-diff-side 'left)
  docker
  treemacs

  ;; 补全
  (auto-completion :variables
                   auto-completion-enable-snippets-in-popup t
                   auto-completion-enable-sort-by-usage t)

  ;; Org-mode
  (org :variables
       org-enable-roam-support t)

  ;; UI
  (colors :variables
          colors-colorize-identifiers 'variables)
  )

2.5 从零开始的最小配置

如果你想自己从头构建配置,以下是一个最小但完整的起步模板:

minimal-init.el

;;; minimal-init.el --- 最小启动配置 -*- lexical-binding: t; -*-

;;; 基础设置
;; 禁用启动画面
(setq inhibit-startup-message t)

;; 禁用 GUI 元素
(tool-bar-mode -1)
(menu-bar-mode -1)
(scroll-bar-mode -1)

;; 编码设置
(set-language-environment "UTF-8")
(prefer-coding-system 'utf-8)

;; 基本编辑行为
(setq-default
 indent-tabs-mode nil       ; 使用空格缩进
 tab-width 4                ; Tab 宽度
 fill-column 80             ; 自动换行列数
 cursor-type 'bar           ; 光标样式
 )

;; 显示设置
(global-display-line-numbers-mode 1)    ; 行号
(column-number-mode 1)                  ; 列号
(show-paren-mode 1)                     ; 括号匹配
(electric-pair-mode 1)                  ; 自动括号配对
(global-hl-line-mode 1)                 ; 高亮当前行

;; 文件管理
(setq make-backup-files nil)            ; 禁用备份文件
(setq auto-save-default nil)            ; 禁用自动保存
(setq create-lockfiles nil)             ; 禁用锁文件

;; 自定义键位
(global-set-key (kbd "C-=") 'text-scale-increase)
(global-set-key (kbd "C--") 'text-scale-decrease)

;; 包管理设置
(require 'package)
(setq package-archives
      '(("melpa" . "https://melpa.org/packages/")
        ("gnu"   . "https://elpa.gnu.org/packages/")
        ("nongnu" . "https://elpa.nongnu.org/nongnu/")))
(package-initialize)

;; use-package(Emacs 29+ 内置)
(require 'use-package)
(setq use-package-always-ensure t)

;;; 提供模块
(provide 'minimal-init)
;;; minimal-init.el ends here

验证配置

# 使用指定配置文件启动 Emacs
emacs -q -l ~/.emacs.d/minimal-init.el

# 或者使用 --debug-init 调试启动错误
emacs --debug-init

2.6 配置调试技巧

常见启动问题排查

问题原因解决方案
启动卡住包下载超时设置代理或使用镜像源
配置报错Elisp 语法错误--debug-init 启动
字体缺失未安装字体安装对应字体包
编码问题locale 设置不正确设置 LANG=en_US.UTF-8
包冲突多个包功能冲突describe-mode 检查

MELPA 镜像配置(国内加速)

;; 使用清华大学镜像
(setq package-archives
      '(("melpa" . "https://mirrors.tuna.tsinghua.edu.cn/elpa/melpa/")
        ("gnu"   . "https://mirrors.tuna.tsinghua.edu.cn/elpa/gnu/")
        ("nongnu" . "https://mirrors.tuna.tsinghua.edu.cn/elpa/nongnu/")))

调试配置的实用命令

;; 查看变量当前值
C-h v gc-cons-threshold RET

;; 查看当前所有已加载的次模式
C-h m

;; 查看某个按键绑定
C-h k C-x C-f

;; 查看加载了哪些文件
M-x list-load-path-shadows

;; 重新加载配置文件
M-x load-file RET ~/.emacs.d/init.el

2.7 本章小结

要点说明
版本选择推荐 Emacs 29+,内置 use-package 和 Tree-sitter
发行版Doom(Vim 风格)、Spacemacs(全栈)、自建(灵活)
配置结构early-init.el → init.el → 各功能模块
镜像加速国内用户建议配置清华镜像源
调试技巧--debug-initdescribe-modeload-file

2.8 扩展阅读


← 上一章 第 01 章:Emacs 简介 | 下一章 → 第 03 章:基本操作