# 环境搭建

<cite>
**本文引用的文件**
- [package.json](file://package.json)
- [README.md](file://README.md)
- [next.config.ts](file://next.config.ts)
- [tsconfig.json](file://tsconfig.json)
- [tailwind.config.ts](file://tailwind.config.ts)
- [postcss.config.mjs](file://postcss.config.mjs)
- [electron/main.ts](file://electron/main.ts)
- [electron/preload.ts](file://electron/preload.ts)
- [scripts/build-electron.mjs](file://scripts/build-electron.mjs)
- [electron-builder.json](file://electron-builder.json)
- [.npmrc](file://.npmrc)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向开发者，帮助你在本地完成 Forge 项目的环境搭建与开发调试。内容覆盖系统要求、依赖安装、开发配置（TypeScript、Next.js、Electron）、开发服务器启动方式、常用开发工具建议以及常见问题排查。

## 项目结构
Forge 是一个基于 Electron + Next.js 的桌面应用，采用 pnpm 作为包管理器，使用 TypeScript 进行类型约束，并通过 Tailwind CSS 和 PostCSS 构建样式体系。构建流程中，Next.js 以 standalone 模式输出，Electron 主进程负责启动本地服务并与渲染进程通信。

```mermaid
graph TB
subgraph "应用层"
UI["Next.js 应用<br/>src/app/*"]
CMP["React 组件<br/>src/components/*"]
end
subgraph "桌面层"
MAIN["Electron 主进程<br/>electron/main.ts"]
PRELOAD["预加载脚本<br/>electron/preload.ts"]
BUILDER["打包配置<br/>electron-builder.json"]
end
subgraph "构建与工具"
NEXTCFG["Next 配置<br/>next.config.ts"]
TSCFG["TypeScript 配置<br/>tsconfig.json"]
TWCFG["Tailwind 配置<br/>tailwind.config.ts"]
PCFG["PostCSS 配置<br/>.npmrc + postcss.config.mjs"]
BUILDELEC["Electron 构建脚本<br/>scripts/build-electron.mjs"]
end
UI --> MAIN
CMP --> MAIN
MAIN --> PRELOAD
MAIN --> NEXTCFG
UI --> TSCFG
CMP --> TSCFG
UI --> TWCFG
UI --> PCFG
MAIN --> BUILDELEC
BUILDELEC --> BUILDER
```

图表来源
- [next.config.ts:1-13](file://next.config.ts#L1-L13)
- [tsconfig.json:1-24](file://tsconfig.json#L1-L24)
- [tailwind.config.ts:1-36](file://tailwind.config.ts#L1-L36)
- [postcss.config.mjs:1-10](file://postcss.config.mjs#L1-L10)
- [electron/main.ts:1-311](file://electron/main.ts#L1-L311)
- [electron/preload.ts:1-24](file://electron/preload.ts#L1-L24)
- [scripts/build-electron.mjs:1-399](file://scripts/build-electron.mjs#L1-L399)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)

章节来源
- [README.md:343-382](file://README.md#L343-L382)

## 核心组件
- 包管理与脚本：使用 pnpm，提供开发、构建、打包等脚本；对特定原生依赖进行仅构建策略。
- Next.js 配置：以 standalone 输出，禁用压缩以适配本地 Electron 场景，外部化部分包避免打包问题。
- TypeScript 配置：严格模式、增量编译、路径别名、模块解析策略等。
- Tailwind/PostCSS：内容扫描范围、主题变量映射、自动前缀。
- Electron 主进程：在开发模式下连接本地 Next 开发服务器，在生产模式下启动独立服务器并内嵌 Node 运行时。
- Electron 预加载：通过 contextBridge 暴露安全的 API，供渲染进程调用系统能力。
- 打包与分发：electron-builder 配置产物、资源拷贝、签名钩子、平台目标。

章节来源
- [package.json:13-26](file://package.json#L13-L26)
- [package.json:60-66](file://package.json#L60-L66)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [tsconfig.json:2-23](file://tsconfig.json#L2-L23)
- [tailwind.config.ts:3-36](file://tailwind.config.ts#L3-L36)
- [postcss.config.mjs:1-10](file://postcss.config.mjs#L1-L10)
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [scripts/build-electron.mjs:1-399](file://scripts/build-electron.mjs#L1-L399)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)

## 架构总览
下图展示了开发与运行时的关键交互：开发模式下 Electron 直接访问本地 Next 开发服务器；生产模式下 Electron 启动独立的 Next 服务器进程，并通过内嵌 Node 运行时确保原生模块兼容。

```mermaid
sequenceDiagram
participant Dev as "开发者终端"
participant Pnpm as "pnpm 脚本"
participant Electron as "Electron 主进程"
participant NextDev as "Next.js 开发服务器"
participant Standalone as "Next.js 独立服务器"
Dev->>Pnpm : 运行开发脚本
Pnpm->>NextDev : 启动 Next 开发服务器
Pnpm->>Electron : 启动 Electron 并等待 Next 就绪
Electron->>NextDev : 访问 http : //localhost : 3000
Note over Electron,NextDev : 开发模式
Dev->>Pnpm : 运行构建/打包脚本
Pnpm->>Standalone : 生成 .next/standalone
Pnpm->>Electron : 构建 Electron 主进程与预加载
Electron->>Standalone : 启动独立服务器进程
Note over Electron,Standalone : 生产模式
```

图表来源
- [package.json:14-17](file://package.json#L14-L17)
- [electron/main.ts:272-289](file://electron/main.ts#L272-L289)
- [scripts/build-electron.mjs:381-399](file://scripts/build-electron.mjs#L381-L399)

## 详细组件分析

### 系统要求与前置条件
- Node.js：开发与构建均需 Node.js 20+（生产打包阶段会内嵌 Node.js 运行时）。
- pnpm：版本 9+，用于安装与管理依赖。
- Claude Code CLI：已安装且认证，确保 IM Bridge 与相关功能可用。
- 操作系统：官方发布页标注 macOS arm64（Apple Silicon）；Intel Mac 可通过源码打包。

章节来源
- [README.md:44-48](file://README.md#L44-L48)
- [README.md:270-277](file://README.md#L270-L277)

### 依赖安装与包管理器选择
- 使用 pnpm 安装依赖，仓库中对特定原生依赖启用“仅构建”策略，减少不必要的二进制下载与安装成本。
- .npmrc 中开启 hoist 提升，有助于简化依赖树布局。

章节来源
- [package.json:60-66](file://package.json#L60-L66)
- [.npmrc:1-2](file://.npmrc#L1-L2)

### TypeScript 配置要点
- 严格模式、跳过库检查、增量编译、模块解析策略为 bundler，路径别名为 @/*。
- 排除 node_modules、dist-electron、out、release 等目录，避免类型检查污染。

章节来源
- [tsconfig.json:2-23](file://tsconfig.json#L2-L23)

### Next.js 配置要点
- 输出模式为 standalone，便于 Electron 内嵌运行。
- 关闭压缩以适配本地开发场景；图片优化关闭；serverExternalPackages 外部化原生依赖。
- 与 Tailwind/PostCSS 协同工作，内容扫描指向 src 目录。

章节来源
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [tailwind.config.ts:4](file://tailwind.config.ts#L4)
- [postcss.config.mjs:1-10](file://postcss.config.mjs#L1-L10)

### Electron 配置要点
- 开发模式：直接访问 http://localhost:3000。
- 生产模式：启动独立服务器进程，使用内嵌 Node.js 运行时，扩展 PATH 以发现系统工具（如 claude CLI）。
- 预加载脚本通过 contextBridge 暴露安全 API，包括目录选择、文件系统监听、剪贴板读取、数据目录查询等。

章节来源
- [electron/main.ts:8-30](file://electron/main.ts#L8-L30)
- [electron/main.ts:272-289](file://electron/main.ts#L272-L289)
- [electron/main.ts:85-103](file://electron/main.ts#L85-L103)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)

### 构建与打包流程
- Electron 主进程与预加载由 esbuild 构建，目标为 Node.js 环境。
- 生成 .next/standalone 后，执行符号链接解析、pnpm hoisting 修复、外部依赖补齐、隐私路径清理、模板复制、Node 运行时打包与原生模块重建。
- electron-builder 配置产物、资源拷贝、签名钩子、平台目标（macOS dmg/dir、Windows nsis、Linux AppImage）。

章节来源
- [scripts/build-electron.mjs:6-32](file://scripts/build-electron.mjs#L6-L32)
- [scripts/build-electron.mjs:34-73](file://scripts/build-electron.mjs#L34-L73)
- [scripts/build-electron.mjs:88-155](file://scripts/build-electron.mjs#L88-L155)
- [scripts/build-electron.mjs:157-202](file://scripts/build-electron.mjs#L157-L202)
- [scripts/build-electron.mjs:214-292](file://scripts/build-electron.mjs#L214-L292)
- [scripts/build-electron.mjs:294-336](file://scripts/build-electron.mjs#L294-L336)
- [scripts/build-electron.mjs:338-379](file://scripts/build-electron.mjs#L338-L379)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)

### 开发服务器启动方法
- 并行启动：同时启动 Next.js 开发服务器与 Electron，Next 在 3000 端口，Electron 等待 Next 就绪后启动。
- 分别启动：先启动 Next 开发服务器，再启动 Electron 开发脚本。
- 全量构建：先构建 Next.js，再构建 Electron 并使用 electron-builder 打包。

章节来源
- [package.json:14-17](file://package.json#L14-L17)
- [package.json:18-25](file://package.json#L18-L25)

### VSCode 开发工具推荐
- 插件建议：TypeScript TSServer、ESLint、Prettier、Tailwind CSS IntelliSense、PostCSS Language Support、EditorConfig for VS Code。
- 调试配置：可参考以下步骤在 VSCode 中调试 Electron 主进程与预加载脚本（具体配置文件未在仓库中提供，可按常规 Electron 项目设置）。
  - 在主进程入口 electron/main.ts 设置断点，使用 Electron 主进程调试任务。
  - 在预加载脚本 electron/preload.ts 设置断点，使用预加载调试任务。
  - 在 Next.js 开发服务器上设置断点，使用浏览器或 VSCode 的前端调试工具。
- 工作区设置：启用路径映射与类型检查，确保编辑器识别 @/* 别名。

章节来源
- [tsconfig.json:17-19](file://tsconfig.json#L17-L19)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)

## 依赖关系分析
- Electron 主进程依赖 Next.js standalone 产物与内嵌 Node 运行时。
- Next.js 通过 serverExternalPackages 外部化原生依赖，避免打包问题。
- 打包脚本负责补齐缺失的外部依赖与处理 pnpm hoisting 带来的解析问题。
- electron-builder 控制最终产物与资源拷贝。

```mermaid
graph LR
TS["TypeScript 编译<br/>tsconfig.json"] --> NEXT["Next.js 构建<br/>next.config.ts"]
NEXT --> STANDALONE[".next/standalone"]
STANDALONE --> BUILDELEC["Electron 构建脚本<br/>scripts/build-electron.mjs"]
BUILDELEC --> NODERUNTIME["内嵌 Node.js 运行时"]
BUILDELEC --> EXTERNALS["外部依赖补齐"]
NODERUNTIME --> ELECTRONMAIN["Electron 主进程<br/>electron/main.ts"]
EXTERNALS --> ELECTRONMAIN
ELECTRONMAIN --> PRELOAD["预加载脚本<br/>electron/preload.ts"]
BUILDELEC --> BUILDER["electron-builder.json"]
```

图表来源
- [tsconfig.json:2-23](file://tsconfig.json#L2-L23)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [scripts/build-electron.mjs:381-399](file://scripts/build-electron.mjs#L381-L399)
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)

章节来源
- [scripts/build-electron.mjs:338-379](file://scripts/build-electron.mjs#L338-L379)
- [next.config.ts:9](file://next.config.ts#L9)

## 性能考虑
- Next.js 关闭压缩以适配本地开发与流式传输场景。
- 使用 esbuild 构建 Electron 主进程与预加载，提升构建速度。
- electron-builder 使用 asar 打包并仅解包原生 .node 文件，平衡体积与性能。
- 内嵌 Node.js 运行时避免用户环境差异导致的原生模块不兼容问题。

章节来源
- [next.config.ts:5](file://next.config.ts#L5)
- [scripts/build-electron.mjs:6-32](file://scripts/build-electron.mjs#L6-L32)
- [electron-builder.json:56-61](file://electron-builder.json#L56-L61)

## 故障排除指南
- claude 命令不可用
  - 现象：启动应用时报错提示无法找到 claude 命令。
  - 处理：全局安装并登录 Claude Code CLI，确认命令可用后再启动应用。
  - 参考：[README.md:297-305](file://README.md#L297-L305)
- macOS 首次启动 Gatekeeper 警告
  - 现象：首次打开 Forge.app 弹出安全警告。
  - 处理：右键打开、系统设置中允许、或使用命令清除扩展属性。
  - 参考：[README.md:278-291](file://README.md#L278-L291)
- 数据存储位置
  - 说明：应用数据位于用户目录下的固定路径，包含数据库与上传文件。
  - 参考：[README.md:307-316](file://README.md#L307-L316)
- IM Bridge 不需要公网 IP
  - 说明：所有平台均使用出站连接，无需公网 IP 或端口暴露。
  - 参考：[README.md:324-333](file://README.md#L324-L333)
- 开发服务器未就绪导致 Electron 启动失败
  - 现象：Electron 启动时报错，提示无法连接到 Next.js 服务器。
  - 处理：确认 Next.js 开发服务器已在 3000 端口启动，或检查防火墙与端口占用；必要时重启开发脚本。
  - 参考：[package.json:14-17](file://package.json#L14-L17)
- 原生模块不兼容
  - 现象：打包后运行时报错，提示原生模块 ABI 不匹配。
  - 处理：构建脚本会尝试使用内嵌 Node 版本重建原生模块；若失败，检查 Node 版本与平台一致性。
  - 参考：[scripts/build-electron.mjs:294-336](file://scripts/build-electron.mjs#L294-L336)
- pnpm hoisting 导致模块解析失败
  - 现象：运行时找不到某些依赖。
  - 处理：构建脚本会扫描并补齐缺失的 hoisted 依赖；若仍失败，清理缓存后重试。
  - 参考：[scripts/build-electron.mjs:88-155](file://scripts/build-electron.mjs#L88-L155)
- 本地路径泄露风险
  - 说明：构建脚本会替换 standalone 输出中的开发机绝对路径，防止隐私泄露。
  - 参考：[scripts/build-electron.mjs:157-202](file://scripts/build-electron.mjs#L157-L202)

## 结论
通过以上步骤，你可以完成 Forge 的环境搭建与开发调试。建议优先使用 pnpm 与仓库提供的脚本，确保 Next.js 与 Electron 的协同工作；在生产打包阶段，依赖构建脚本与 electron-builder 的配置，保障跨平台分发的一致性与稳定性。

## 附录
- 快速开始命令
  - 安装依赖：pnpm install
  - 开发模式：pnpm dev
  - 构建：pnpm build
  - 打包（macOS）：pnpm package
- 常用脚本说明
  - dev:next：启动 Next.js 开发服务器（Turbopack）
  - dev:electron：编译 Electron 并在 Next 就绪后启动 Electron
  - dev：并行启动 Next 与 Electron
  - build:next/build:electron/build：分别构建 Next、Electron 与全量构建
  - package/package:mac/package:win/package:linux：打包各平台产物

章节来源
- [README.md:50-56](file://README.md#L50-L56)
- [package.json:13-26](file://package.json#L13-L26)