---
title: "Debian / Ubuntu 使用 xcaddy 自定义编译 Caddy"
tags: ['Debian', 'Ubuntu', 'Caddy', 'Caddy Server', 'xcaddy']
published: 2023-01-22 23:54:54
updated: 2023-01-22 00:00:00
excerpt: "本文将指导使用 xcaddy 自定义编译 Caddy。"
---
> 本文件是烧饼博客文章的 Markdown 原文，正式版本见 https://u.sb/xcaddy/
> 全站文章与页面索引见 https://u.sb/llms.txt，建议先读索引再继续抓取。

本文将指导使用 xcaddy 自定义编译 Caddy。

以下操作需要 root 权限，本文命令均已带上 `sudo` 前缀，请确保当前用户拥有 `sudo` 权限；或者直接使用 root 用户操作并省略命令中的 `sudo`。

上一篇文章介绍了如何[安装使用 Caddy](/debian-install-caddy/)，但是 Caddy 的功能有时候并不能满足业务需求，如果想要使用更多的功能，就需要自定义编译 Caddy。

[xcaddy](https://github.com/caddyserver/xcaddy) 是 Caddy 官方制作的用于自定义编译 Caddy 的工具，它可以帮助我们快速的编译出符合自己需求的 Caddy。

## 安装 xcaddy

我们按照官方的[安装方法](https://caddyserver.com/docs/install#debian-ubuntu-raspbian)，首先，安装一些必要的软件包：

```bash
sudo apt update
sudo apt upgrade -y
sudo apt install curl vim wget gnupg dpkg apt-transport-https lsb-release ca-certificates
```

然后按照[官方教程](https://go.dev/doc/install)安装 Go：

```bash
wget https://go.dev/dl/go1.24.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.5.linux-amd64.tar.gz
```

然后把 go 加入系统环境变量：

```bash
echo "export PATH=\$PATH:/usr/local/go/bin" | sudo tee -a /etc/profile
```

然后加入 Caddy 的 GPG 公钥和 apt 源：

```bash
curl -sSL https://dl.cloudsmith.io/public/caddy/xcaddy/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/xcaddy.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/xcaddy.gpg] https://dl.cloudsmith.io/public/caddy/xcaddy/deb/debian any-version main" | sudo tee /etc/apt/sources.list.d/xcaddy.list
```

Debian 下也可以使用 extrepo：

```bash
sudo apt install extrepo
sudo extrepo enable caddyserver
```

然后更新系统后即可安装 xcaddy：

```bash
sudo apt update
sudo apt install xcaddy
```

重启打开 SSH 后检查一下 go 和 xcaddy 的版本：

```bash
root@debian ~ # go version
go version go1.24.5 linux/amd64

root@debian ~ # xcaddy version
v0.4.5 h1:7E4b+3Gm2do/WpuDXh5MWIj+qgCCvQqR487Sm8C6hwc=
```

## 自定义编译 Caddy

我们可以选择一些自己喜欢的模块，比如[缓存模块](https://github.com/caddyserver/cache-handler)和 [Brotli 压缩模块](https://github.com/ueffel/caddy-brotli)：

```bash
xcaddy build \
    --with github.com/caddyserver/cache-handler \
	  --with github.com/ueffel/caddy-brotli
```

经过一段时间的编译以后，我们就可以在当前目录下看到一个名为 `caddy` 的二进制文件，这就是我们自定义编译的 Caddy 了。

## 自定义 Caddy 和系统 Caddy 共存

如果我们想要自定义 Caddy 和系统 Caddy 共存，可以使用官方的[教程](https://caddyserver.com/docs/build)：

首先，按照我们的教程[安装](/debian-install-caddy/) Caddy，安装完毕后，先停止 Caddy 服务：

```bash
sudo systemctl stop caddy
```

然后使用 `dpkg-divert` 命令将系统 Caddy 的二进制文件移动到 `/usr/bin/caddy.default` 并做软链接：

```bash
sudo dpkg-divert --divert /usr/bin/caddy.default --rename /usr/bin/caddy
```

然后把我们自己编译好的 Caddy 二进制文件移动到 `/usr/bin/caddy.custom`：

```bash
sudo mv ./caddy /usr/bin/caddy.custom
```

然后设置优先级，让我们的自定义 Caddy 优先启动：

```bash
sudo update-alternatives --install /usr/bin/caddy caddy /usr/bin/caddy.default 10
sudo update-alternatives --install /usr/bin/caddy caddy /usr/bin/caddy.custom 50
```

此时我们可以看到默认的 `/usr/bin/caddy` 已经是我们自定义的 Caddy 了：

```bash
root@debian ~ # ls -l /usr/bin/caddy
lrwxrwxrwx 1 root root 23 Jan 22 10:52 /usr/bin/caddy -> /etc/alternatives/caddy*

root@debian ~ # ls -l /etc/alternatives/caddy
lrwxrwxrwx 1 root root 21 Jan 22 10:52 /etc/alternatives/caddy -> /usr/bin/caddy.custom
```

我们也可以使用 `sudo update-alternatives --config caddy` 命令来切换系统安装的 Caddy 和自定义的 Caddy：

```bash
root@caddy ~ # update-alternatives --config caddy
There are 2 choices for the alternative caddy (providing /usr/bin/caddy).

  Selection    Path                    Priority   Status
------------------------------------------------------------
* 0            /usr/bin/caddy.custom    50        auto mode
  1            /usr/bin/caddy.custom    50        manual mode
  2            /usr/bin/caddy.default   10        manual mode

Press <enter> to keep the current choice[*], or type selection number:
```

我们可以看到默认的 Caddy 二进制文件是我们自定义的，你可以输入 0 (按照优先级自动) 1 (手工切换自定义 Caddy) 或 2 (使用系统默认 Caddy) 来修改并切换默认的 Caddy 版本。