docker_start.ps1¶

文档编写日期: 2026-03-20

使用办法 (Usage)¶

基本语法¶

.\scripts\build_helpers\docker_start.ps1 [OPTIONS]

参数说明¶

参数	类型	默认值	说明
`-Arch`	String	`amd64`	目标架构，可选值: `amd64` 或 `arm64`
`-FastBuild`	Switch	-	跳过镜像清理，复用已有镜像
`-Interactive`	Switch	-	进入交互式Shell (默认行为)
`-Verify`	Switch	-	运行CI构建验证
`-BuildProject`	Switch	-	构建镜像 + 执行完整清理构建
`-BuildProjectFast`	Switch	-	构建镜像 + 执行快速构建
`-RunProjectTest`	Switch	-	构建镜像 + 运行测试
`-StayOnError`	Switch	-	CI失败时保留容器用于调试
`-NoLog`	Switch	-	禁用文件日志 (默认记录日志)
`-Help`	Switch	-	显示帮助信息

使用示例¶

# 默认: 进入交互式Shell
.\scripts\build_helpers\docker_start.ps1

# 运行CI构建验证
.\scripts\build_helpers\docker_start.ps1 -Verify

# CI失败时保留容器调试
.\scripts\build_helpers\docker_start.ps1 -Verify -StayOnError

# 构建镜像 + 完整清理构建
.\scripts\build_helpers\docker_start.ps1 -BuildProject

# 构建镜像 + 快速构建
.\scripts\build_helpers\docker_start.ps1 -BuildProjectFast

# 构建镜像 + 运行测试
.\scripts\build_helpers\docker_start.ps1 -RunProjectTest

# ARM64架构构建
.\scripts\build_helpers\docker_start.ps1 -Arch arm64

# 复用已有镜像 (快速模式)
.\scripts\build_helpers\docker_start.ps1 -FastBuild

# 禁用日志记录
.\scripts\build_helpers\docker_start.ps1 -NoLog

Scripts详解¶

脚本用途¶

本脚本用于在Docker容器中构建CFDesktop项目，提供： - 跨平台构建环境 (amd64/arm64) - 隔离的编译环境 - CI构建验证 - 交互式开发环境

依赖模块¶

LibPaths.psm1 - 提供路径解析和项目根目录定位功能

配置文件¶

使用架构特定的CI配置文件： - amd64: build_ci_config.ini - arm64: build_ci_aarch64_config.ini

执行模式¶

1. 交互模式 (默认)¶

启动容器并进入交互式bash shell：

.\docker_start.ps1

项目根目录挂载到容器内的 /project。

2. CI验证模式¶

运行完整的CI构建：

.\docker_start.ps1 -Verify

执行 scripts/build_helpers/ci_build_entry.sh ci

3. 构建项目模式¶

完整构建: 清理 + 配置 + 编译
```
.\docker_start.ps1 -BuildProject
```
快速构建: 配置 + 编译 (无清理)
```
.\docker_start.ps1 -BuildProjectFast
```

4. 测试模式¶

运行项目测试：

.\docker_start.ps1 -RunProjectTest

架构支持¶

amd64¶

原生x86_64构建
使用 linux_gcc_64 Qt版本
平台: linux/amd64

arm64¶

ARM64原生容器
使用 linux_gcc_arm64 Qt版本
平台: linux/arm64
在x86_64主机上使用QEMU模拟 (较慢但产生原生ARM64二进制)

Docker镜像¶

镜像名称: cfdesktop-build
Dockerfile: scripts/docker/Dockerfile.build
构建上下文: 项目根目录

构建参数¶

参数	用途
`QT_ARCH`	Qt架构 (linux_gcc_64 / linux_gcc_arm64)
`INSTALL_DEPS`	是否安装依赖 (交互模式为0)

日志功能¶

默认启用日志记录： - 日志目录: scripts/docker/logger/ - 文件格式: ci_build_YYYYMMDD_HHMMSS.log - 内容: 构建过程的完整输出

使用 -NoLog 参数禁用日志。

安全检查¶

Docker存在性检查
Docker守护进程运行状态检查

退出代码¶

0 - 操作成功
非0 - 操作失败

调试功能¶

使用 -StayOnError 参数，CI构建失败时容器不会退出，可进入交互模式调试：

.\docker_start.ps1 -Verify -StayOnError

快速构建模式¶

使用 -FastBuild 参数复用已有镜像： - 镜像存在时跳过构建 - 镜像不存在时才会构建

UI输出格式¶

脚本使用彩色输出： - 青色 - 标题/阶段名称 - 绿色 - 成功信息 - 红色 - 错误信息 - 黄色 - 警告信息 - 蓝色 - 强调信息 - 暗灰色 - 次要信息

注意事项¶

首次运行需要构建Docker镜像，可能需要较长时间
ARM64构建在x86_64主机上使用QEMU模拟，速度较慢
项目目录以卷挂载方式映射到容器，修改会立即生效
容器内工作目录为 /project