自定义 Forgejo 的前端界面

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

环境

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

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

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'

关注这一行：

    volumes:
      - ./forgejo:/data

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

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

更换 Logo

根据 Forgejo 的官方文档，要覆盖 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 容器，清除缓存，查看效果。

docker compose down
docker compose up -d

更改首页模板

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

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

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

{{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 相关的配置：

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

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

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

参考资料

2026-02-21