# 快速开始
**本文引用的文件**
- `README.md`
- `package.json`
- `angular.json`
- `src-tauri/tauri.conf.json`
- `src-tauri/Cargo.toml`
- `src-tauri/build.rs`
- `src/main.ts`
- `src/app/app.component.ts`
- `scripts/build-mac-store.sh`
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向新加入的开发者，帮助你在本地快速搭建 GSDJGXApp 的开发与构建环境。项目采用 Angular 22 + Tauri 2 + Rust 的跨平台桌面应用架构，前端负责交互与可视化，后端使用 Rust 提供高性能计算与系统能力，通过 Tauri 桥接实现桌面应用的原生体验。
## 项目结构
项目采用“前端 + 桌面壳（Tauri/Rust）”的双层结构：
- 前端：Angular 应用，位于 src/ 目录，构建产物输出至 dist/gsdjgxapp/browser
- 桌面壳：Tauri 应用，位于 src-tauri/ 目录，包含 Rust 逻辑、配置与资源
- 构建脚本：根目录 package.json 提供统一的开发与构建脚本入口
- 文档与脚本：docs/ 提供系统文档，scripts/ 提供自动化脚本（如 Mac App Store 打包）
```mermaid
graph TB
subgraph "前端(浏览器)"
A["Angular 应用
src/"]
B["构建产物
dist/gsdjgxapp/browser"]
end
subgraph "桌面壳(Tauri/Rust)"
C["Tauri 配置
src-tauri/tauri.conf.json"]
D["Rust 依赖与入口
src-tauri/Cargo.toml / src/main.rs"]
E["构建桥接
src-tauri/build.rs"]
end
subgraph "构建与脚本"
F["包管理与脚本
package.json"]
G["文档与脚本
docs/, scripts/"]
end
A --> B
F --> A
F --> C
C --> D
D --> E
F --> D
G -.-> A
G -.-> C
```
图表来源
- `angular.json#L1-L79`
- `src-tauri/tauri.conf.json#L1-L70`
- `src-tauri/Cargo.toml#L1-L66`
- `src-tauri/build.rs#L1-L4`
- `package.json#L1-L90`
章节来源
- `README.md#L1-L118`
- `angular.json#L1-L79`
- `src-tauri/tauri.conf.json#L1-L70`
- `src-tauri/Cargo.toml#L1-L66`
- `package.json#L1-L90`
## 核心组件
- 前端框架与构建
- Angular 22 + TypeScript，使用 @angular-devkit/build-angular:application 构建
- 开发服务器端口固定为 1420，便于 Tauri dev 模式联调
- 桌面壳与系统能力
- Tauri 2 作为桌面应用壳，Rust 提供高性能计算与系统插件（文件系统、对话框、剪贴板、日志、进程、SQL、更新器等）
- Rust 版本要求 ≥ 1.70，启用增量编译关闭以提升稳定性
- 构建与打包
- 前端构建输出到 dist/gsdjgxapp/browser，由 Tauri 在构建阶段注入
- 支持多目标打包（NSIS、Windows WebView 安装模式等），并可启用自动更新
章节来源
- `angular.json#L14-L61`
- `src-tauri/tauri.conf.json#L6-L11`
- `src-tauri/Cargo.toml#L26-L66`
- `package.json#L13-L16`
## 架构概览
下图展示了开发与构建过程中的关键交互：前端开发服务器、Tauri 开发模式、Rust 插件与系统能力之间的关系。
```mermaid
sequenceDiagram
participant Dev as "开发者"
participant FE as "前端开发服务器
Angular Dev Server"
participant TA as "Tauri 开发模式"
participant RS as "Rust 插件与能力"
participant OS as "操作系统"
Dev->>FE : "pnpm start"
FE-->>Dev : "监听端口 1420"
Dev->>TA : "pnpm tauri dev"
TA->>FE : "加载 devUrl http : //localhost : 1420"
TA->>RS : "调用插件(文件/对话框/日志/进程/SQL/更新器)"
RS-->>TA : "返回结果与事件"
TA-->>Dev : "桌面窗口运行(热重载/调试)"
Dev->>TA : "pnpm tauri build"
TA->>FE : "执行 beforeBuildCommand(pnpm build)"
TA->>OS : "打包产物(NSIS/Updater/图标)"
```
图表来源
- `src-tauri/tauri.conf.json#L6-L11`
- `angular.json#L47-L61`
- `package.json#L4-L16`
- `src-tauri/Cargo.toml#L26-L66`
## 详细组件分析
### 前端开发服务器（仅 UI）
- 启动方式：pnpm start
- 行为说明：启动 Angular Dev Server，监听端口 1420；适合纯前端开发与调试
- 适用场景：UI/UX 开发、组件测试、样式与路由调试
章节来源
- `README.md#L53-L61`
- `angular.json#L47-L61`
- `package.json#L6`
### 桌面应用开发环境（推荐）
- 启动方式：pnpm tauri dev
- 行为说明：Tauri 在 dev 模式下，先执行 beforeDevCommand（pnpm start），再加载 devUrl（http://localhost:1420）；同时注入 Rust 插件能力
- 适用场景：需要系统能力（文件、对话框、日志、进程、SQL、更新器）联调的桌面应用开发
章节来源
- `README.md#L53-L61`
- `src-tauri/tauri.conf.json#L6-L11`
- `package.json#L12`
### 生产构建与打包
- 构建方式：pnpm tauri build
- 行为说明：先执行 beforeBuildCommand（pnpm build），生成前端产物；随后由 Tauri 打包为桌面应用（NSIS 等），并可启用自动更新
- 适用场景：生成可分发的桌面应用安装包
章节来源
- `README.md#L63-L67`
- `src-tauri/tauri.conf.json#L6-L11`
- `package.json#L13`
### Mac App Store 专用构建脚本
- 脚本用途：编译、签名并打包为 .pkg，用于提交到 Mac App Store
- 关键特性：自动处理版本号同步、证书与 Provisioning Profile 校验、Entitlements 注入、多目标签名与打包
- 适用场景：向 Mac App Store 提交应用
章节来源
- `scripts/build-mac-store.sh#L1-L492`
- `src-tauri/tauri.conf.json#L30-L51`
### Rust 插件与系统能力清单
- 已启用插件：文件系统、对话框、HTTP、进程、存储、剪贴板、深链、日志、更新器（非移动端）
- 语言与版本：Rust 1.94+（`rust-version = "1.94"`，sqlx 0.9 / SeaORM 2.0 最低要求），启用增量编译关闭（提高稳定性）
- 适用场景：文件操作、外部链接、日志记录、进程控制、SQLite 数据持久化、应用更新
章节来源
- `src-tauri/Cargo.toml#L26-L66`
- `src-tauri/tauri.conf.json#L52-L68`
### 前端引导与许可证注册
- 引导流程：在 main.ts 中注册中文本地化与 Syncfusion 许可证，随后引导应用启动
- 适用场景：确保 UI 组件正确显示与授权
章节来源
- `src/main.ts#L1-L23`
### 深度链接与更新机制
- 深度链接：桌面端支持自定义协议（gsdjgxapp），可用于外部唤起与数据导入
- 自动更新：启用更新器插件，配置更新端点与公钥，支持桌面端自动升级
章节来源
- `src-tauri/tauri.conf.json#L52-L68`
- `src/app/app.component.ts#L1-L200`
## 依赖关系分析
- 前端与桌面壳的耦合点
- Tauri 配置中定义了 devUrl 与构建前钩子，保证前端开发与桌面壳联调的一致性
- Rust 插件通过 Tauri 暴露给前端调用，形成“前端 UI + Rust 能力”的协作关系
- 包管理与脚本
- package.json 统一管理脚本入口，简化开发与构建流程
- scripts/ 提供额外的自动化任务（如 Mac App Store 打包）
```mermaid
graph LR
P["package.json
脚本入口"] --> A["Angular Dev Server
端口 1420"]
P --> T["Tauri 开发/构建"]
T --> C["tauri.conf.json
devUrl/beforeBuildCommand"]
T --> R["Rust 插件(Cargo.toml)"]
A --> D["dist/gsdjgxapp/browser"]
T --> D
```
图表来源
- `package.json#L4-L16`
- `src-tauri/tauri.conf.json#L6-L11`
- `src-tauri/Cargo.toml#L26-L66`
章节来源
- `package.json#L1-L90`
- `src-tauri/tauri.conf.json#L1-L70`
## 性能考虑
- 前端构建
- 生产构建开启输出哈希与体积预算，有助于控制包体大小与缓存策略
- Rust 计算与 I/O
- 启用增量编译关闭，减少开发期编译不确定性
- 使用 SeaORM 与 SQLite 进行结构化数据持久化，结合异步 Tokio 运行时提升并发性能
- 桌面应用窗口
- 配置透明、可调整尺寸与标题栏 Overlay，兼顾美观与可用性
章节来源
- `angular.json#L29-L45`
- `src-tauri/Cargo.toml#L61-L66`
- `src-tauri/tauri.conf.json#L14-L29`
## 故障排除指南
- Node.js 版本过低
- 现象：安装或启动时报错
- 解决：升级 Node.js 至 22+，并清理缓存后重试安装
- pnpm 版本过低
- 现象：安装依赖失败或脚本报错
- 解决：升级 pnpm 至 11+，确保使用 pnpm install
- Rust 工具链缺失或版本过低
- 现象：Tauri 构建失败或 Cargo 报错（如 `rustc x.x.x is not supported by the following packages`）
- 解决：安装/升级 Rust 1.94+（`rustup update stable`），并确保 cargo 可用
- macOS 系统依赖缺失
- 现象：Tauri 构建或签名失败
- 解决：安装 Xcode Command Line Tools（xcode-select --install）
- Tauri 构建前置条件不足
- 现象：桌面应用无法启动或打包失败
- 解决：安装 Apple 开发者工具链（macOS），并确保 @tauri-apps/cli 可用
- 前端端口冲突
- 现象：pnpm start 启动失败
- 解决：检查端口 1420 是否被占用，或在 angular.json 中调整端口后重启
- Tauri dev 模式无法加载前端
- 现象：桌面应用窗口空白或报错
- 解决：确认 beforeDevCommand 成功执行且前端在 http://localhost:1420 可访问
- Mac App Store 打包失败
- 现象：签名或打包阶段报错
- 解决：检查证书与 Provisioning Profile、Team ID、Entitlements，确保与 Bundle ID 一致
章节来源
- `README.md#L35-L44`
- `angular.json#L47-L61`
- `src-tauri/tauri.conf.json#L6-L11`
- `scripts/build-mac-store.sh#L171-L281`
## 结论
通过本指南，你可以完成 GSDJGXApp 的环境准备、项目克隆、安装与启动，并理解前端开发与桌面应用开发两种模式的差异与适用场景。生产构建与 Mac App Store 专用脚本可帮助你生成高质量的可分发产物。遇到问题时，可依据“故障排除指南”逐项排查。
## 附录
### 快速开始步骤
- 克隆与安装
- git clone <你的仓库地址>
- cd GSDJGXApp
- pnpm install
- 开发环境启动
- 前端开发（仅 UI）：pnpm start
- 桌面应用开发（推荐）：pnpm tauri dev
- 构建生产版本
- pnpm tauri build
章节来源
- `README.md#L45-L67`
- `package.json#L4-L16`
### 常用脚本说明
- start：启动 Angular Dev Server（仅前端）
- build：构建前端产物（dist）
- watch：开发持续构建（无 Tauri）
- test/test:watch/test:coverage：单元测试相关
- tauri dev：启动桌面开发环境
- tauri build：构建生产桌面应用
- release/release:mac-store/upload/release:upload：发布相关
章节来源
- `README.md#L69-L79`
- `package.json#L4-L16`
### 目录结构与关键文件
- src/
- 前端源码与入口，包含 main.ts、应用组件与路由等
- src-tauri/
- Tauri 配置（tauri.conf.json）、Rust 依赖（Cargo.toml）、构建桥接（build.rs）、资源与权限
- dist/
- 前端构建产物（dist/gsdjgxapp/browser）
- scripts/
- 自动化脚本（如 Mac App Store 打包脚本）
- docs/
- 项目文档与设计说明
章节来源
- `src/main.ts#L1-L23`
- `src-tauri/tauri.conf.json#L1-L70`
- `src-tauri/Cargo.toml#L1-L66`
- `src-tauri/build.rs#L1-L4`
- `scripts/build-mac-store.sh#L1-L492`