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-init、describe-mode、load-file |
2.8 扩展阅读
← 上一章 第 01 章:Emacs 简介 | 下一章 → 第 03 章:基本操作