Mac/Win双平台实战从源码构建Gitea的深度技术指南最近在帮团队搭建内部代码托管平台时我决定尝试从源码编译安装Gitea。这个决定让我在Mac和Windows系统上经历了截然不同的配置过程也遇到了不少值得记录的坑点。本文将详细分享我的完整实践过程包括Node.js和Go环境的配置细节以及如何解决跨平台编译中的各种问题。1. 环境准备跨平台的基础配置1.1 Go语言环境搭建Go语言是Gitea的后端基础版本要求至少1.16以上。在Mac上安装Go相对简单# 使用Homebrew安装 brew install go # 验证安装 go versionWindows用户则需要手动下载安装包。我推荐使用Scoop包管理器# 安装Scoop如果尚未安装 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser irm get.scoop.sh | iex # 安装Go scoop install go关键环境变量配置变量名Mac配置Windows配置GOPATHexport GOPATH$HOME/go系统环境变量中添加GOPATH%USERPROFILE%\goPATHexport PATH$PATH:$GOPATH/bin在Path中添加%GOPATH%\bin提示Windows用户安装后务必重启终端或执行refreshenv命令使环境变量生效1.2 Node.js环境配置前端构建需要Node.js环境版本要求≥12.17。Mac用户同样可以使用Homebrewbrew install nodeWindows用户建议使用nvm-windows管理多版本# 安装nvm-windows choco install nvm # 安装指定版本Node.js nvm install 16.14.2 nvm use 16.14.2验证安装node -v npm -v2. 源码获取与依赖安装2.1 克隆Gitea仓库无论哪种平台都需要先将Gitea源码克隆到GOPATH指定目录mkdir -p $GOPATH/src/code.gitea.io cd $GOPATH/src/code.gitea.io git clone https://github.com/go-gitea/gitea.git cd giteaWindows用户需要注意确保Git Bash或PowerShell中$GOPATH变量已正确设置路径中的斜杠方向可能需要调整2.2 前端依赖安装进入项目根目录后首先安装前端依赖npm install常见问题解决权限错误在命令前加sudoMac/Linux或以管理员身份运行终端Windows网络超时更换npm源为国内镜像npm config set registry https://registry.npmmirror.comnode-sass编译失败确保Python环境已安装Windows可能需要安装windows-build-tools3. 跨平台编译实战3.1 Mac平台编译在Mac上编译相对顺利主要命令如下# 构建后端M1芯片需要额外参数 TAGSbindata make backend # 生成可执行文件后运行 ./gitea webM1/M2芯片用户可能遇到的问题# 如果出现架构不匹配错误需要指定arm64架构 GOARCHarm64 TAGSbindata make backend3.2 Windows平台编译Windows编译过程较为复杂需要特别注意首先安装必要的构建工具choco install make编译命令与Mac类似但需要注意# 需要指定GCC路径如果使用MinGW set PATHC:\MinGW\bin;%PATH% # 执行编译 $env:TAGSbindata; make backend常见错误处理缺少gcc安装MinGW或TDM-GCCsqlite3编译失败安装pkg-config并设置PKG_CONFIG_PATH权限不足以管理员身份运行PowerShell4. 数据库配置与优化Gitea支持多种数据库我推荐使用MySQL 8.0。以下是跨平台安装建议4.1 Mac安装MySQLbrew install mysql8.0 brew services start mysql8.04.2 Windows安装MySQL使用官方安装包或Chocolateychoco install mysql --version8.0.31初始化数据库CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER gitealocalhost IDENTIFIED BY your_password; GRANT ALL PRIVILEGES ON gitea.* TO gitealocalhost; FLUSH PRIVILEGES;4.3 Gitea数据库配置首次运行./gitea web后访问http://localhost:3000进入安装界面。数据库配置要点连接字符串gitea:your_passwordtcp(localhost:3306)/gitea?charsetutf8mb4parseTimeTruelocLocal字符集务必选择utf8mb4以支持完整Unicode内存设置根据服务器配置调整小型团队建议[database] MAX_IDLE_CONNS 10 CONN_MAX_LIFETIME 18005. 生产环境部署建议5.1 反向代理配置推荐使用Nginx或Caddy作为反向代理Nginx示例配置server { listen 80; server_name git.yourdomain.com; location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }5.2 服务化运行Mac (launchd):!-- ~/Library/LaunchAgents/io.gitea.plist -- ?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringio.gitea/string keyProgramArguments/key array string/path/to/gitea/string stringweb/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ /dict /plistWindows (NSSM):nssm install Gitea # 在弹出的GUI中设置路径和参数6. 高级配置与调优6.1 邮件通知设置[mailer] ENABLED true HOST smtp.yourmail.com:587 FROM giteayourdomain.com USER giteayourdomain.com PASSWD your_password6.2 缓存优化[cache] ADAPTER redis HOST redis://localhost:6379/06.3 定期维护任务设置cron或计划任务执行# 每日凌晨执行仓库检查 gitea doctor --all --log-file/var/log/gitea/doctor.log在实际部署中我发现Windows平台对长路径的支持仍然存在问题建议将仓库存储在较浅的目录结构中。而Mac平台则需要注意SIP(System Integrity Protection)可能对某些目录的写入限制。
Mac/Win双平台实测：从源码编译安装Gitea的完整踩坑记录（含Node.js和Go环境配置）
发布时间：2026/5/19 15:30:45
Mac/Win双平台实战从源码构建Gitea的深度技术指南最近在帮团队搭建内部代码托管平台时我决定尝试从源码编译安装Gitea。这个决定让我在Mac和Windows系统上经历了截然不同的配置过程也遇到了不少值得记录的坑点。本文将详细分享我的完整实践过程包括Node.js和Go环境的配置细节以及如何解决跨平台编译中的各种问题。1. 环境准备跨平台的基础配置1.1 Go语言环境搭建Go语言是Gitea的后端基础版本要求至少1.16以上。在Mac上安装Go相对简单# 使用Homebrew安装 brew install go # 验证安装 go versionWindows用户则需要手动下载安装包。我推荐使用Scoop包管理器# 安装Scoop如果尚未安装 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser irm get.scoop.sh | iex # 安装Go scoop install go关键环境变量配置变量名Mac配置Windows配置GOPATHexport GOPATH$HOME/go系统环境变量中添加GOPATH%USERPROFILE%\goPATHexport PATH$PATH:$GOPATH/bin在Path中添加%GOPATH%\bin提示Windows用户安装后务必重启终端或执行refreshenv命令使环境变量生效1.2 Node.js环境配置前端构建需要Node.js环境版本要求≥12.17。Mac用户同样可以使用Homebrewbrew install nodeWindows用户建议使用nvm-windows管理多版本# 安装nvm-windows choco install nvm # 安装指定版本Node.js nvm install 16.14.2 nvm use 16.14.2验证安装node -v npm -v2. 源码获取与依赖安装2.1 克隆Gitea仓库无论哪种平台都需要先将Gitea源码克隆到GOPATH指定目录mkdir -p $GOPATH/src/code.gitea.io cd $GOPATH/src/code.gitea.io git clone https://github.com/go-gitea/gitea.git cd giteaWindows用户需要注意确保Git Bash或PowerShell中$GOPATH变量已正确设置路径中的斜杠方向可能需要调整2.2 前端依赖安装进入项目根目录后首先安装前端依赖npm install常见问题解决权限错误在命令前加sudoMac/Linux或以管理员身份运行终端Windows网络超时更换npm源为国内镜像npm config set registry https://registry.npmmirror.comnode-sass编译失败确保Python环境已安装Windows可能需要安装windows-build-tools3. 跨平台编译实战3.1 Mac平台编译在Mac上编译相对顺利主要命令如下# 构建后端M1芯片需要额外参数 TAGSbindata make backend # 生成可执行文件后运行 ./gitea webM1/M2芯片用户可能遇到的问题# 如果出现架构不匹配错误需要指定arm64架构 GOARCHarm64 TAGSbindata make backend3.2 Windows平台编译Windows编译过程较为复杂需要特别注意首先安装必要的构建工具choco install make编译命令与Mac类似但需要注意# 需要指定GCC路径如果使用MinGW set PATHC:\MinGW\bin;%PATH% # 执行编译 $env:TAGSbindata; make backend常见错误处理缺少gcc安装MinGW或TDM-GCCsqlite3编译失败安装pkg-config并设置PKG_CONFIG_PATH权限不足以管理员身份运行PowerShell4. 数据库配置与优化Gitea支持多种数据库我推荐使用MySQL 8.0。以下是跨平台安装建议4.1 Mac安装MySQLbrew install mysql8.0 brew services start mysql8.04.2 Windows安装MySQL使用官方安装包或Chocolateychoco install mysql --version8.0.31初始化数据库CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER gitealocalhost IDENTIFIED BY your_password; GRANT ALL PRIVILEGES ON gitea.* TO gitealocalhost; FLUSH PRIVILEGES;4.3 Gitea数据库配置首次运行./gitea web后访问http://localhost:3000进入安装界面。数据库配置要点连接字符串gitea:your_passwordtcp(localhost:3306)/gitea?charsetutf8mb4parseTimeTruelocLocal字符集务必选择utf8mb4以支持完整Unicode内存设置根据服务器配置调整小型团队建议[database] MAX_IDLE_CONNS 10 CONN_MAX_LIFETIME 18005. 生产环境部署建议5.1 反向代理配置推荐使用Nginx或Caddy作为反向代理Nginx示例配置server { listen 80; server_name git.yourdomain.com; location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }5.2 服务化运行Mac (launchd):!-- ~/Library/LaunchAgents/io.gitea.plist -- ?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringio.gitea/string keyProgramArguments/key array string/path/to/gitea/string stringweb/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ /dict /plistWindows (NSSM):nssm install Gitea # 在弹出的GUI中设置路径和参数6. 高级配置与调优6.1 邮件通知设置[mailer] ENABLED true HOST smtp.yourmail.com:587 FROM giteayourdomain.com USER giteayourdomain.com PASSWD your_password6.2 缓存优化[cache] ADAPTER redis HOST redis://localhost:6379/06.3 定期维护任务设置cron或计划任务执行# 每日凌晨执行仓库检查 gitea doctor --all --log-file/var/log/gitea/doctor.log在实际部署中我发现Windows平台对长路径的支持仍然存在问题建议将仓库存储在较浅的目录结构中。而Mac平台则需要注意SIP(System Integrity Protection)可能对某些目录的写入限制。
