GitLab自托管实例前端机制及自定义修改咨询

Hey there! 作为后端开发者刚接触GitLab前端自定义确实会有点懵，我来一步步给你捋清楚～

一、你需要掌握的核心开发语言 #

GitLab的前端栈围绕Ruby on Rails框架构建，核心要了解这几样：

• HAML：GitLab的页面模板用HAML编写，是HTML的简化版，语法简洁还能和Ruby逻辑紧密结合，上手很快
• SCSS：样式用SCSS（Sass的扩展），支持变量、嵌套、混合宏，方便维护全局和组件样式
• JavaScript/Vue.js：GitLab的交互功能（比如Issue面板、MR评论区）大量用Vue组件，懂基础JS语法和Vue组件化思想就够用
• 基础Ruby：模板里会嵌少量Ruby逻辑（比如条件判断、循环），懂点基础能看懂动态内容的生成逻辑

二、Bitnami GitLab的关键文件目录结构 #

Bitnami部署的GitLab默认安装在/opt/bitnami/gitlab，核心目录如下：

• app/views/：存放所有HAML模板，按功能模块划分（比如app/views/projects/对应项目页面模板，app/views/layouts/是全局布局模板）
• app/assets/stylesheets/：SCSS样式文件，application.scss是全局入口，子目录对应不同页面/组件的样式（比如pages/projects/是项目页面专属样式）
• app/assets/javascripts/：JS脚本和Vue组件，application.js是全局入口，vue/目录下是所有Vue组件文件
• config/locales/：多语言文本配置文件（比如en.yml、zh-CN.yml），大部分页面文本都在这里定义，优先改这里比硬改模板更灵活
• public/：静态资源目录，放图片、字体、静态HTML等文件
• vendor/assets/：第三方依赖的样式和脚本，不建议修改，GitLab升级时会被覆盖

三、如何注释不需要展示的内容 #

根据文件类型不同，注释方式也不一样：

1. HAML模板文件 #

HAML有两种常用注释：

• 单行注释：用-#开头，完全不会被渲染成HTML

  -# 这行内容不会出现在页面上
  %h1 这是会正常显示的标题
  

• 块级注释：用/开头，能包裹一整块内容

  /
    .unwanted-block
      %p 这块区域的所有内容都会被注释，不会渲染
  

2. SCSS样式文件 #

和普通CSS注释规则一致：

• 单行注释：// 这行样式不会生效
• 多行注释：/* 这块样式全部不会被加载 */

3. Vue/JavaScript文件 #

和标准JS/Vue语法一致：

• 单行注释：// 这行代码不会执行
• 多行注释：/* 这块代码不会被运行 */
• Vue模板里的HTML注释：<!-- 这部分模板内容不会渲染 -->

四、修改设计与文本的实操方法 #

1. 修改页面文本 #

优先改多语言配置文件，避免硬编码：

• 找到config/locales/下对应语言的YAML文件（比如中文是zh-CN.yml），搜索文本对应的键值对修改，比如：

  # 例子：修改项目页面的"New Issue"文本
  projects:
    issues:
      new: "创建新问题"
  

• 如果是模板里的硬编码文本，直接打开对应的HAML文件修改即可（比如app/views/projects/issues/_new.html.haml）

2. 修改页面设计（样式与布局） #

• 全局样式调整：在app/assets/stylesheets/application.scss末尾添加自定义样式，覆盖默认样式，比如：

  // 修改全局导航栏背景色
  .navbar-gitlab {
    background-color: #2c3e50 !important;
  }
  

• 页面特定样式：找到对应页面的SCSS文件（比如项目页面是app/assets/stylesheets/pages/projects.scss），添加或修改样式
• 布局调整：打开对应的HAML模板，调整DOM结构，比如移除不需要的模块、调整元素顺序

五、官方文档与学习路径 #

• GitLab自托管实例自带开发文档，直接访问你的实例域名+/help/development/frontend 就能看到前端开发指南，里面详细讲了HAML语法、Vue组件规范、样式规范
• Bitnami的GitLab部署文档在本地/opt/bitnami/docs/gitlab目录下，有关于自定义和维护的说明
• 学习顺序建议先从HAML入手，语法简单很快能看懂模板结构；再学基础Vue，理解组件化开发逻辑

六、重要注意事项 #

• 修改文件前一定要备份，比如：

  sudo cp /opt/bitnami/gitlab/app/views/layouts/application.html.haml /opt/bitnami/gitlab/app/views/layouts/application.html.haml.bak
  

• GitLab升级时，自定义的源码文件可能会被覆盖，复杂修改建议用GitLab的自定义主题（适合样式和少量文本修改），或者把修改提交到自己的GitLab fork分支，升级时合并差异
• 修改后需要重启GitLab服务生效：

  sudo /opt/bitnami/ctlscript.sh restart gitlab
  

内容的提问来源于stack exchange，提问作者syncastra