Skip to content

INSTALL.md

Latest commit

 

History

History
105 lines (69 loc) · 4.69 KB

INSTALL.md

File metadata and controls

105 lines (69 loc) · 4.69 KB
Raw

环境安装指南

本文档是项目的安装总入口。新机流程分为 Stage 0 与 Stage 1；无参数 install.ps1 仍保留为仓库工具准备入口，不会隐式执行完整装机。

Stage 0：平台基础环境

根据你的操作系统，先完成对应的平台安装：

Stage 0 负责获得 Git、平台包管理器、仓库与 PowerShell 7。PowerShell 7 可用后，平台入口把控制权交给根 Stage 1；它不维护 Core/Full 步骤列表。

仓库工具准备（兼容入口）

pwsh ./install.ps1

无参数调用保持原行为：配置 PATH、同步 bin shim、构建 Bash/Node 工具，并执行仓库开发环境准备。现有 pnpm pwsh:install 与 pnpm scripts:install 继续使用该入口。

Stage 1：统一安装编排器

只有显式传入 -Preset Core|Full 才进入 Stage 1：

# 查看当前平台的步骤、支持状态和未来叶子路径
pwsh ./install.ps1 -ListSteps
pwsh ./install.ps1 -ListSteps -OutputFormat Json

# 预览或执行预设
pwsh ./install.ps1 -Preset Core -WhatIf
pwsh ./install.ps1 -Preset Full -NetworkMode Direct

# 精准重跑，不自动展开依赖
pwsh ./install.ps1 -Preset Core -Step core-cli

# 假定前序步骤已完成，从指定步骤继续
pwsh ./install.ps1 -Preset Core -FromStep core-cli

# 排除步骤；依赖被排除时，下游返回 Blocked
pwsh ./install.ps1 -Preset Full -SkipStep full-apps

根目录 pnpm 快捷入口

以下命令适用于 Stage 0 已完成，且当前环境已经可以使用 Node.js、pnpm 与 PowerShell 7 的情况。它们不会替代三个平台的 Stage 0；Windows、macOS 与 Linux/WSL 均使用相同命令，由根 install.ps1 自动识别当前系统。

# 列出当前平台步骤
pnpm provision:list

# 只读预览
pnpm provision:core:preview
pnpm provision:full:preview

# 执行当前平台安装
pnpm provision:core
pnpm provision:full

需要覆盖默认网络模式、交互模式或步骤范围时，直接在脚本名后继续传入 install.ps1 参数：

pnpm provision:core -NetworkMode China
pnpm provision:full -FromStep full-apps -NonInteractive

provision:* 表示按仓库清单配置当前系统，避免与 pnpm 内置的 install 命令重名。无参数的 pnpm pwsh:install 与 pnpm scripts:install 仍仅用于仓库开发工具准备，不等价于 Core 或 Full 装机。

Stage 1 固定顺序为 03 sources、04 shell、05 core-cli、06 fonts、07 profile-tools、08 full-apps、09 platform-automation、10 login-items、11 desktop-integration、99 verify。Core 选择 03～07 与 99；Full 追加 08～11。

步骤串行执行。失败只阻断依赖步骤，独立步骤和可执行的 verify 继续。平台不支持的步骤为 Skipped；声明支持但真实叶子尚未接入时为 Blocked。退出码为：成功/预览 0、执行失败 1、参数错误 2、仅 Blocked 10。

网络模式与恢复

  • Direct：默认模式，不创建 source 事务。
  • China：保留事务，汇总输出 transaction ID 与 Restore 命令。
  • Auto：需要镜像时创建临时事务，编排器在成功、失败或异常路径的 finally 中 Restore。
  • Auto Restore 失败时整体至少为 Blocked；若安装步骤已经 Failed，原始失败仍保持最高优先级。

-OutputFormat Json 的 stdout 只包含一个 JSON document，叶子日志不会混入标准输出。-Unattended 与 -NonInteractive 互斥；-WhatIf 不创建 source 事务，也不写用户配置。

macOS、Linux/WSL 与 Windows 的真实叶子均已接入。Windows 11 22H2+ x64 和 Windows 10 22H2 x64 支持 Core/Full；Windows ARM64 和 Server 返回明确 Partial/Blocked。Linux 完整支持 Ubuntu/Debian、Arch、WSL 客体与 amd64，ARM 返回明确 Blocked。声明支持但入口缺失时不会回退旧脚本伪报完整成功。

旧应用安装入口

pwsh ./install.ps1 -installApp

该入口迁移期内输出弃用提示，不映射为 Full，也不能与 Preset 或步骤参数组合。Linux 兼容分支调用新的 Core CLI 叶子；新机应直接使用 -Preset Core|Full。

单独安装 PowerShell 模块

  • 脚本: profile/installer/installModules.ps1
  • 执行方式: pwsh ./profile/installer/installModules.ps1
  • 前置条件: 步骤 1 完成
  • 可跳过: 是
  • 说明: 安装 Pester 等 PowerShell 模块

可选：Nix 开发环境

仓库提供可选 nix develop 工具链（不接入 Core/Full）。见 nix-devshell.md。