AList跨平台编译指南：Windows/macOS/Linux全支持

AList作为一款支持多存储的文件列表程序（File List Program），凭借其丰富的存储适配能力和跨平台特性，已成为个人与企业文件管理的重要工具。本文将详细介绍如何在Windows、macOS和Linux三大主流操作系统上编译AList，让你轻松掌握从源码到可执行文件的全流程。

项目简介与编译准备

AList支持本地存储、阿里云盘、OneDrive等多种存储类型，其源码基于Go语言开发，采用Gin框架和Solidjs构建前端界面。编译前需确保系统已安装以下环境：

• Go 1.18+（推荐1.20版本以上，国内Go镜像站）
• Git（用于拉取源码）
• 相关系统依赖（各平台差异见表1）

项目核心编译配置文件：

• 构建脚本：build.sh（虽未直接读取，但根据Dockerfile推断存在）
• 入口脚本：entrypoint.sh
• 主程序入口：main.go

graph TD
    A[源码拉取] --> B[依赖安装]
    B --> C[编译配置]
    C --> D[跨平台编译]
    D --> E[输出可执行文件]
    E --> F[运行测试]

各平台编译步骤

Windows平台编译

环境准备：

• 安装Go：从Go官网下载Windows安装包
• 安装Git：Git for Windows
• 安装MinGW-w64：提供GCC等编译工具链

编译命令：

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/alis/alist.git
cd alist

# 设置Windows编译环境
set GOOS=windows
set GOARCH=amd64
set CGO_ENABLED=1

# 安装依赖
go mod download

# 执行编译
go build -ldflags="-s -w" -o bin/alist-windows-amd64.exe main.go

编译产物位于bin/alist-windows-amd64.exe，可直接双击运行或通过命令行启动：

./alist-windows-amd64.exe server

macOS平台编译

环境准备：

• 安装Xcode Command Line Tools：

  xcode-select --install
  

• 安装Go：使用Homebrew brew install go 或从官网下载

编译命令：

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/alis/alist.git
cd alist

# 设置macOS编译环境
export GOOS=darwin
export GOARCH=arm64  # M系列芯片
# 或 x86_64架构: export GOARCH=amd64

# 编译
go build -ldflags="-s -w" -o bin/alist-darwin-arm64 main.go

编译完成后可在bin目录找到可执行文件，赋予执行权限并运行：

chmod +x bin/alist-darwin-arm64
./bin/alist-darwin-arm64 server

Linux平台编译

环境准备：

• 安装依赖：

  # Debian/Ubuntu
  sudo apt update && sudo apt install -y git golang gcc libc6-dev
  # CentOS/RHEL
  sudo dnf install -y git golang gcc glibc-devel
  

编译命令：

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/alis/alist.git
cd alist

# 设置Linux编译环境
export GOOS=linux
export GOARCH=amd64
export CGO_ENABLED=1

# 使用官方构建脚本（推荐）
bash build.sh release linux

Docker编译方案（适用于任何Linux发行版）：

# 构建Docker镜像
docker build -t alist-builder -f Dockerfile .

# 从容器中提取编译产物
docker run --rm -v $(pwd)/bin:/app/bin alist-builder cp /app/bin/alist /app/bin/

编译配置与优化

关键编译参数

AList编译支持多种自定义参数，通过-ldflags传递：

• -s -w：移除符号表和调试信息，减小二进制体积
• -X main.version=v3.28.0：指定版本号
• -X main.commit=abc123：嵌入Git提交哈希

示例：

go build -ldflags "-s -w -X main.version=v3.28.0 -X main.commit=$(git rev-parse HEAD)" main.go

交叉编译配置

如需在一个平台编译其他平台的产物，可通过环境变量指定目标系统：

目标平台	GOOS	GOARCH	备注
Windows	windows	amd64	需MinGW支持CGO
Windows	windows	386	32位系统
macOS	darwin	amd64	Intel芯片
macOS	darwin	arm64	Apple Silicon
Linux	linux	amd64	最常用架构
Linux	linux	arm64	树莓派4/5等
Linux	linux	mipsle	路由器设备

常见问题解决

编译错误：依赖下载失败

解决方案：配置Go模块代理

go env -w GOPROXY=https://goproxy.cn,direct
go mod download

执行错误：文件权限不足

解决方案：

# Linux/macOS
chmod +x alist
# Windows：右键属性-安全-编辑权限

Windows防火墙提示

首次运行时需允许AList通过防火墙，否则可能无法访问Web界面（默认端口5244）。

自动化编译与部署

使用Docker编译（跨平台通用）

AList提供完整的Docker化编译流程，无需手动配置环境：

# 构建镜像
docker build -t alist .

# 运行容器
docker run -d -p 5244:5244 -v /etc/alist:/opt/alist/data --name alist alist

Dockerfile关键步骤解析：

1. 使用Alpine作为基础镜像，安装Go编译环境
2. 执行go mod download下载依赖
3. 运行build.sh release docker完成编译
4. 多阶段构建减小最终镜像体积

CI/CD集成

可通过GitHub Actions或GitLab CI实现自动编译，参考项目中.github/workflows/build.yml配置（推断存在），主要流程：

1. 代码推送触发构建
2. 多平台并行编译
3. 自动生成Release资产
4. 推送Docker镜像到仓库

总结与展望

通过本文介绍的方法，你可以在三大主流操作系统上成功编译AList。项目采用Go语言的跨平台特性，配合精心设计的构建脚本，使得编译过程简单高效。未来，AList团队将进一步优化编译流程，可能会：

• 提供预编译的交叉编译工具链
• 简化Windows平台的CGO依赖
• 增加更多架构支持（如RISC-V）

如需获取最新编译指南或提交改进建议，请参考官方文档README_cn.md或参与项目贡献指南。

编译过程中遇到问题？欢迎在项目讨论区留言，或查阅常见问题解答。

pie
    title AList编译平台分布
    "Linux" : 65
    "Windows" : 20
    "macOS" : 15

希望本文能帮助你顺利编译和使用AList，如有任何改进建议，欢迎提交PR参与项目共建！