⚙️ 配置 Config

控制安装器行为的结构体——装到哪、要不要 sudo、用不用代理、装哪个版本、要不要顺带装 PHP。

包路径：github.com/scagogogo/composer-skills/pkg/installer

Config 结构体

type Config struct {
    DownloadURL         string // Composer 安装脚本下载地址
    InstallPath         string // Composer 安装目录
    UseProxy            bool   // 是否使用代理下载
    ProxyURL            string // 代理服务器 URL
    TimeoutSeconds      int    // 下载/安装超时（秒）
    UseSudo             bool   // 是否使用 sudo/管理员权限（Unix 系）
    PreferBrewOnMac     bool   // macOS 上是否优先用 Homebrew
    PreferPackageManager bool  // Linux 上是否优先用系统包管理器
    AutoInstallPHP      bool   // 缺 PHP 时是否自动安装
    TargetVersion       string // 目标版本："latest"/"1"/"2"/"preview"/"2.5.1"
}

字段详解

字段	类型	默认值（DefaultConfig）	说明
`DownloadURL`	`string`	`https://getcomposer.org/installer`	拉取 `composer-setup.php` 的地址
`InstallPath`	`string`	Windows: `%ProgramFiles%\Composer`；darwin/linux: `/usr/local/bin`	Composer 落地目录
`UseProxy`	`bool`	`false`	下载是否走代理
`ProxyURL`	`string`	空	代理 URL，配合 `UseProxy`
`TimeoutSeconds`	`int`	`300`	下载/安装超时秒数
`UseSudo`	`bool`	`false`	写入系统目录时是否用 sudo（macOS/linux/unix 生效）
`PreferBrewOnMac`	`bool`	`true`	macOS 上先试 `brew install composer`
`PreferPackageManager`	`bool`	`true`	Linux 上先试 apt/dnf/pacman 等
`AutoInstallPHP`	`bool`	`true`	缺 PHP 时自动通过包管理器装 PHP
`TargetVersion`	`string`	`latest`	指定安装版本；空字符串等价于 `latest`

两个预设构造器

DefaultConfig

返回适合当前 OS 的通用默认配置。

func DefaultConfig() Config

特点：

✅ macOS 与 Linux 都启用 PreferBrewOnMac / PreferPackageManager / AutoInstallPHP。
⚠️ UseSudo=false——写入 /usr/local/bin 在多数桌面 Linux 上需要手动开 sudo 或改 DefaultConfig().UseSudo=true。

SmartConfig

在 DefaultConfig 基础上按 OS 进一步优化，给出「最可能一次成功」的配置。

func SmartConfig() Config

OS	SmartConfig 调整
🍎 darwin	`PreferBrewOnMac=true`、`AutoInstallPHP=true`
🐧 linux	`PreferPackageManager=true`、`AutoInstallPHP=true`、`UseSudo=true`
🪟 windows	`PreferPackageManager=false`、`AutoInstallPHP=false`（直接下载 phar，不碰 PHP）

何时用 SmartConfig

大多数「无脑装上」场景直接用 SmartConfig()。它把 Linux 默认开 sudo、Windows 关掉 PHP 自动装，避免在 Windows 上因找不到包管理器而报错。

DefaultConfig vs SmartConfig 对比

字段	DefaultConfig（linux/darwin）	SmartConfig（linux）	SmartConfig（darwin）	SmartConfig（windows）
`InstallPath`	`/usr/local/bin`	`/usr/local/bin`	`/usr/local/bin`	`%ProgramFiles%\Composer`
`UseSudo`	`false`	`true`	`false`	`false`
`PreferBrewOnMac`	`true`	`true`	`true`	`false`
`PreferPackageManager`	`true`	`true`	`true`	`false`
`AutoInstallPHP`	`true`	`true`	`true`	`false`
`TargetVersion`	`latest`	`latest`	`latest`	`latest`
`TimeoutSeconds`	`300`	`300`	`300`	`300`

核心差异：SmartConfig 让 Linux 开 sudo、Windows 不依赖包管理器也不自动装 PHP——两条最常踩坑的路径都被默认规避。

安装路径

OS	默认 InstallPath	可执行产物
🪟 Windows	`%ProgramFiles%\Composer`	`composer.phar` + `composer.bat`（需手动加 PATH）
🍎 darwin	`/usr/local/bin`	`composer.phar` + `composer`（shell 包装脚本）
🐧 linux	`/usr/local/bin`	`composer.phar` + `composer`（shell 包装脚本）

composer 包装脚本内容为 #!/bin/sh\nphp "<phar>" "$@"，Windows 的 .bat 为 @php "<phar>" %*。

是否使用 sudo

UseSudo=true 时：

写文件改用 sudo tee / echo ... | sudo tee。
chmod 改用 sudo chmod。
包管理器命令前加 sudo。
删除文件用 sudo rm -f。

UseSudo=false 时全部走普通文件操作；目标目录不可写会返回 ErrInsufficientRights。

容器环境

CI 容器、Docker 镜像通常已是 root，sudo 可能不存在或行为异常。此时显式设 UseSudo=false，并把 InstallPath 指向可写目录（如 /usr/local/bin 在 root 镜像里通常可写）。

是否自动装 PHP

AutoInstallPHP=true 时，Install() / InstallWithProgress() 在 HasPHP() 为否的情况下会：

调 DetectLinuxDistro() 获取发行版与包管理器。
调 InstallPHP(distro, useSudo) 通过对应包管理器装 PHP 及常用扩展（mbstring/xml/curl）。
再次 HasPHP() 验证，仍失败则返回 ErrPHPNotFound。

AutoInstallPHP=false 时，缺 PHP 直接返回 ErrPHPNotFound，不做任何尝试——适合希望严格把控 PHP 来源的环境。

Windows 上不自动装 PHP

Windows 没有统一包管理器，SmartConfig 默认 AutoInstallPHP=false。Windows 用户需自行安装 PHP 并保证 php 在 PATH 中。

快速示例

用 SmartConfig 一键装

package main

import (
    "log"

    "github.com/scagogogo/composer-skills/pkg/installer"
)

func main() {
    inst := installer.NewInstaller(installer.SmartConfig())
    if err := inst.Install(); err != nil {
        log.Fatalf("安装失败: %v", err)
    }
}

自定义路径 + 代理

package main

import (
    "log"

    "github.com/scagogogo/composer-skills/pkg/installer"
)

func main() {
    cfg := installer.DefaultConfig()
    cfg.InstallPath = "/opt/composer/bin"
    cfg.UseProxy = true
    cfg.ProxyURL = "http://127.0.0.1:7890"
    cfg.TimeoutSeconds = 120
    cfg.TargetVersion = "2.5.1"

    inst := installer.NewInstaller(cfg)
    if err := inst.Install(); err != nil {
        log.Fatalf("安装失败: %v", err)
    }
}

运行时切换配置

inst := installer.DefaultInstaller()
// 先查当前配置
cfg := inst.GetConfig()
// 改字段后写回
cfg.UseSudo = true
inst.SetConfig(cfg)

进阶

目标版本语义：TargetVersion 为空或 latest 拉稳定版；preview 拉 preview 版；1/2 拉大版本；形如 2.5.1 拉指定版本的 phar。详见发行版与 PHP 的 InstallComposerVersion。
代理与超时：UseProxy/ProxyURL/TimeoutSeconds 仅影响通过 composerutils.DownloadFile 的下载（如 macOS/unix 直接下载安装脚本）；curl 直连下载（InstallComposerVersion 内部）当前不读代理配置。
配合 SmartInstaller：SmartInstaller 接收的是 InstallOptions，其中 Config 字段即此处的 Config；为空时自动回退到 SmartConfig()。

⚙️ 配置 Config ​

Config 结构体 ​

字段详解 ​

两个预设构造器 ​

DefaultConfig ​

SmartConfig ​

DefaultConfig vs SmartConfig 对比 ​

安装路径 ​

是否使用 sudo ​

是否自动装 PHP ​

快速示例 ​

用 SmartConfig 一键装 ​

自定义路径 + 代理 ​

运行时切换配置 ​

进阶 ​