---
date: "2017-04-15T14:56:00+02:00"
slug: "customizing-gitea"
sidebar_position: 100
aliases:
- /zh-cn/customizing-gitea
---
# 自定义 Gitea
自定义 Gitea 通常通过 `CustomPath` 目录完成。默认情况下，它是工作目录（WorkPath）下的
`custom` 目录，但如果您的[安装方式](../installation/from-binary.md)做了不同设置，也可能位于其他位置。
这是覆盖配置项、模板等内容的核心位置。您可以通过 `gitea help` 查看 `CustomPath`，也可以在
_站点管理_ 页面的 _Configuration_ 选项卡中找到该路径。您还可以通过设置 `GITEA_CUSTOM`
环境变量，或在 `gitea` 二进制上使用 `--custom-path` 选项来覆盖 `CustomPath`。
（命令行选项会覆盖环境变量。）
如果 Gitea 以二进制方式部署，所有默认路径都相对于 Gitea 二进制文件。
如果通过发行版安装，这些路径通常会按照 Linux 文件系统标准进行调整。Gitea 会尝试创建所需目录，
包括 `custom/`。某些发行版可能会通过 `/etc/gitea/` 为 `custom` 提供一个符号链接。
应用配置可以在 `CustomConf` 文件中找到，默认路径为 `$GITEA_CUSTOM/conf/app.ini`，
但如果您的[安装方式](../installation/from-binary.md)修改了配置，也可能位于其他位置。
同样，您可以通过 `gitea help` 查看该变量，也可以使用 `gitea` 二进制的 `--config` 选项覆盖它。
- [快速备忘单](../administration/config-cheat-sheet.md)
- [完整配置清单](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
如果在检查 `gitea help` 后仍找不到 `CustomPath` 目录，请检查 `GITEA_CUSTOM` 环境变量；
它可以用来将默认路径覆盖为其他位置。例如，`GITEA_CUSTOM` 可能由 init 脚本设置。
您也可以在站点管理页面的 “Configuration” 选项卡下检查该值是否已设置。
- [环境变量清单](../administration/environment-variables.md)
:::note
Gitea 必须执行完整重启后，配置更改才会生效。
:::
## 提供自定义公共文件
要让 Gitea 提供自定义公共文件（例如页面和图片），请将 `$GITEA_CUSTOM/public/`
目录作为 webroot。Gitea 会跟随符号链接。
当前仅提供以下文件：
- `public/robots.txt`
- `public/.well-known/` 目录中的文件
- `public/assets/` 目录中的文件
例如，存放在 `$GITEA_CUSTOM/public/assets/` 中的 `image.png` 文件，可以通过
`http://gitea.domain.tld/assets/image.png` 访问。
## 修改 Logo
如果要构建自定义 logo 和/或 favicon，请克隆 Gitea 源码仓库，替换 `assets/logo.svg`
和/或 `assets/favicon.svg`，然后运行 `make generate-images`。`assets/favicon.svg`
仅用于 favicon。执行后会更新以下输出文件，随后您可以将它们放到服务器上的
`$GITEA_CUSTOM/public/assets/img` 中：
- `public/assets/img/logo.svg` - 用于站点图标、应用图标
- `public/assets/img/logo.png` - 用于 Open Graph
- `public/assets/img/avatar_default.png` - 用作默认头像图片
- `public/assets/img/apple-touch-icon.png` - 用于 iOS 设备书签
- `public/assets/img/favicon.svg` - 用于 favicon
- `public/assets/img/favicon.png` - 用作不支持 SVG favicon 的浏览器回退图标
如果源图片不是矢量格式，您可以尝试使用诸如[这个工具](https://www.aconvert.com/image/png-to-svg/)
将光栅图像转换为矢量图。
## 自定义 Gitea 页面和资源
Gitea 可执行文件内置了运行所需的全部资源：模板、图片、样式表和翻译。您可以在 `custom`
目录下放置与原路径一致的替换文件来覆盖其中任意资源。例如，要替换 C++ 仓库默认提供的
`.gitignore`，我们需要替换 `options/gitignore/C++`。为此，您必须将替换文件放到
`$GITEA_CUSTOM/options/gitignore/C++`（`CustomPath` 目录位置见本文开头说明）。
Gitea 的每一个页面都可以修改。动态内容通过 [go template](https://pkg.go.dev/html/template)
生成，您可以通过在 `$GITEA_CUSTOM/templates` 目录下放置替换文件进行修改。
要获取任意内嵌文件（包括模板），可以使用[`gitea embedded` 工具](../administration/cmd-embedded.md)。
另外，也可以在 Gitea 源码仓库的 [`templates`](https://github.com/go-gitea/gitea/tree/main/templates)
目录中找到它们。（注意：示例链接指向 `main` 分支，请确保所使用的模板与您当前的发布版本兼容。）
请注意，任何包含在 `{{` 和 `}}` 中的语句都是 Gitea 的模板语法，
如果您没有完全理解这些组件，就不应修改它们。
### 自定义首页 / 主页
将与您所使用 Gitea 版本对应的 [`home.tmpl`](https://github.com/go-gitea/gitea/blob/main/templates/home.tmpl)
从 `templates` 目录复制到 `$GITEA_CUSTOM/templates`。
随后按您的需要编辑即可。
不要忘记重启 Gitea 以应用更改。
### 添加链接和页签
如果您只是想为顶部导航栏或页脚添加额外链接，或者为仓库视图添加额外页签，
可以将它们分别放入 `$GITEA_CUSTOM/templates/custom/` 目录中的
`extra_links.tmpl`（添加到导航栏的链接）、`extra_links_footer.tmpl`
（添加到页脚左侧的链接）和 `extra_tabs.tmpl`。
例如，假设您在德国，需要添加法律上通常要求提供的 “Impressum”/关于页面，用来说明谁对站点内容负责：
只需将该页面放到 `$GITEA_CUSTOM/public/assets/` 目录中
（例如 `$GITEA_CUSTOM/public/assets/impressum.html`），再在
`$GITEA_CUSTOM/templates/custom/extra_links.tmpl` 或
`$GITEA_CUSTOM/templates/custom/extra_links_footer.tmpl` 中加入指向它的链接即可。
为了匹配当前样式，该链接应使用类名 `item`，并且您可以使用 `{{AppSubUrl}}` 获取基础 URL：
`Impressum`
更多信息请参见[添加法律页面](../administration/adding-legal-pages.md)。
您也可以用同样的方式添加新页签，将其放入 `extra_tabs.tmpl` 中。
与其他页签样式匹配所需的精确 HTML 位于文件 `templates/repo/header.tmpl`
（[GitHub 源码](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl)）。
### 页面中的其他插入内容
除了 `extra_links.tmpl` 和 `extra_tabs.tmpl` 之外，您还可以在
`$GITEA_CUSTOM/templates/custom/` 目录中放置其他有用的模板：
- `header.tmpl`，位于 `` 结束标签之前，例如可用于添加自定义 CSS 文件。
- `body_outer_pre.tmpl`，位于 `` 起始标签之后。
- `body_inner_pre.tmpl`，位于顶部导航栏之前，但已处于主容器 `` 内部。
- `body_inner_post.tmpl`，位于主容器结束之前。
- `body_outer_post.tmpl`，位于底部 `