blob: f02df7ad67c88b127fd2bcc96159fd2dd1e992f5 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
+++
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 的首页长这样，总之…… 很难看。
用上一小节类似的方法，在 `$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/
|
