+++
date = '2026-02-21T23:42:55+08:00'
draft = false
title = '自定义 Forgejo 的前端界面'
+++

[Forgejo](https://forgejo.org/) 是基于 [Gitea](https://about.gitea.com/) 开发的，用 Go 语言编写的轻量级远程 Git 服务，功能很丰富，可以视作 GitHub 的自托管、开源替代。自建的 Forgejo 实例如果和别人的看起来一模一样，未免太没个性，故决定自定义。

## 环境

我使用 Docker 部署 Forgejo，使用 `docker compose` 管理容器，所以不能直接在宿主机上修改 Forgejo 的文件，要把宿主机上的文件挂载到容器内。在容器内部，Forgejo 会读取 `/data` 目录下的文件。

Forgejo 的官方文档提供了 `docker-compose.yml` 的例子：

```yaml
networks:
  forgejo:
    external: false

services:
  server:
    image: codeberg.org/forgejo/forgejo:13
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - '3000:3000'
      - '222:22'
```

关注这一行：

```yaml
    volumes:
      - ./forgejo:/data
```

这里的意思是：把宿主机上的 `./forgejo` 目录挂载到容器内的 `/data` 目录中。简单来说，如果你是用官方提供的 `docker-compose.yml` 安装的 Forgejo，只需要把 `./forgejo` 当成 `/data` 目录就好了。

如果你没有使用 Docker，或者从源代码构建 Forgejo，这篇笔记不适用你的情况。

## 更换 Logo

根据 [Forgejo 的官方文档](https://forgejo.org/docs/next/contributor/customization/#changing-the-logo)，要覆盖 Forgejo 默认的 Logo，需要在 `$FORGEJO_CUSTOM/public/assets/img` 放置这几个文件：

- `public/assets/img/logo.svg` - 用于站点、应用图标
- `public/assets/img/logo.png` - 用于 Open Graph 和主页
- `public/assets/img/favicon.svg` - 用于 favicon
- `public/assets/img/favicon.png` - 有些浏览器不支持 SVG 类型的 favicon，用一个 PNG 图片作为回退

撰写这篇笔记时，我使用的 Forgejo  版本是 `13.0.5+gitea-1.22.0`，此时 `$FORGEJO_CUSTOM` 的默认值是 `/data/gitea`，如果你不修改这个环境变量，你就需要把上述文件放在宿主机的 `.forgejo/gitea/public/assets/img/` 目录下。

如果没有这个目录，需要字形创建。

创建完成之后重启 Docker 容器，清除缓存，查看效果。

```shell
docker compose down
docker compose up -d
```

## 更改首页模板

Forgejo 的首页长这样，总之…… 很难看。

![](https://r2.eltr.ac/jar/forgejo-homepage.png)

用上一小节类似的方法，在 `$FORGEJO_CUSTOM/templates/` 目录下创建特定名称的模板文件，就能替换 Forgejo 使用的模板。想知道自己要替换的模板名称叫什么，可以到 [Forgejo 的源代码](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates)去找。这里我们要修改的是首页，所以是 `home.tmpl`。

创建 `.forgejo/gitea/templates/home.tmpl`，复制源代码中 [home.tmpl](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates/home.tmpl) 的内容，做自己想要的修改。下面这个例子删掉了首页的大部分内容和描述文本，只留下站点 Logo 和站点名。

```html
{{template "base/head" .}}
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home"}}{{end}}" class="page-content home">
	<div class="tw-mb-8 tw-px-8">
		<div class="center">
			<img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}">
			<div class="hero">
				<h1 class="ui icon header title">
					{{AppDisplayName}}
				</h1>
			</div>
		</div>
	</div>
</div>
{{template "base/footer" .}}
```

保存，重启 Docker 容器，访问实例测试效果。

## 自定义 CSS

Forgejo 的 CSS 文件和图片一样属于静态资源，存在于 `assets` 目录下，具体来说是 `$FORGEJO_CUSTOM/public/assets/css/`。所有的主题文件都以 `theme-` 开头，比如默认的 `theme-forgejo-auto.css`。假设我们要创建一个名为 `foo` 的主题，就要创建 `$FORGEJO_CUSTOM/public/assets/css/theme-foo.css`。

这边建议复制 `theme-forgejo-auto.css`，以此基础进行修改。要得到这个文件，可以直接访问：

```
https://<你的_FORGEJO_域名>/assets/css/theme-forgejo-auto.css
```

~~里面有两百多个 CSS 变量，慢慢改吧（~~ 如果没有特别精细的需求，比如只是想换个主题色，可以直接扔给 LLM 改。

准备好 CSS 文件之后，要让 Forgejo 知道有个名为 `foo` 的主题存在。修改 `app.ini` 配置文件，位置一般在 `/data/gitea/conf/app.ini`，对应宿主机上的 `.forgejo/gitea/conf/app.ini`。添加 UI 相关的配置：

```toml
[ui]
THEMES = gitea,arc-green,forgejo-dark,forgejo-light,forgejo-auto,foo
DEFAULT_THEME = foo
```

其中 `THEMES` 告诉 Forgejo 可用的主题有哪些，这些主题会显示在用户的设置项里，用户可以自行选择主题。`DEFAULT_THEME` 就是默认选择的主题，未登录的访客看到的也是这个主题。

完成后重启 Docker 容器，应该能看到改动生效了。

## 参考资料

- https://forgejo.org/docs/next/contributor/customization/
- https://blog.maximlucas.dev/posts/2025-08-28-theming-forgejo/
- https://blog.jakobs.systems/en/blog/20251117-forgejo-customization/