文档记录
This commit is contained in:
JSD\13999
239
docs/guide/unity-package-git-workflow.md
Normal file
239
docs/guide/unity-package-git-workflow.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Unity Package 开发与 Git 分发指南
|
||||
|
||||
## 概述
|
||||
|
||||
本文档描述如何将 Unity 代码组织为 Package 结构，并通过 Git 仓库进行版本管理和分发更新。适用于 FlowScope 框架各模块的独立开发与集成。
|
||||
|
||||
## Package 标准结构
|
||||
|
||||
```text
|
||||
com.flowscope.xxx/
|
||||
├── package.json # 必须 — 包的元数据与依赖声明
|
||||
├── README.md # 包说明
|
||||
├── CHANGELOG.md # 版本变更记录
|
||||
├── LICENSE # 许可证
|
||||
├── Runtime/
|
||||
│ ├── ExampleScript.cs
|
||||
│ └── com.flowscope.xxx.Runtime.asmdef
|
||||
├── Editor/
|
||||
│ └── com.flowscope.xxx.Editor.asmdef
|
||||
├── Tests/
|
||||
│ ├── Runtime/
|
||||
│ │ └── com.flowscope.xxx.Tests.Runtime.asmdef
|
||||
│ └── Editor/
|
||||
│ └── com.flowscope.xxx.Tests.Editor.asmdef
|
||||
└── Samples~/ # 可选示例（~ 后缀表示在 Package Manager 中隐藏）
|
||||
└── Demo/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## package.json 说明
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "com.flowscope.xxx",
|
||||
"version": "0.1.0",
|
||||
"displayName": "FlowScope XXX",
|
||||
"description": "模块描述",
|
||||
"unity": "2022.3",
|
||||
"dependencies": {
|
||||
"com.flowscope.core": "0.1.0"
|
||||
},
|
||||
"author": {
|
||||
"name": "FlowScope Team"
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/flowscope/xxx.git"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
关键字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `name` | 反向域名格式，全局唯一 |
|
||||
| `version` | 语义化版本（SemVer） |
|
||||
| `unity` | 最低兼容 Unity 版本 |
|
||||
| `dependencies` | 该包依赖的其他 Package |
|
||||
|
||||
## 开发工作流
|
||||
|
||||
### 推荐：在 Unity 项目内开发
|
||||
|
||||
直接在目标 Unity 项目的 `Packages/` 目录下创建包文件夹，Unity 自动识别，开发体验与 `Assets/` 中写脚本一致。
|
||||
|
||||
```text
|
||||
MyUnityProject/
|
||||
├── Assets/
|
||||
│ └── Scenes/
|
||||
│ └── Test.unity # 测试场景
|
||||
├── Packages/
|
||||
│ ├── manifest.json
|
||||
│ └── com.flowscope.xxx/ ← 在这里开发
|
||||
│ ├── package.json
|
||||
│ ├── Runtime/
|
||||
│ └── Editor/
|
||||
```
|
||||
|
||||
`manifest.json` 中自动生成引用：
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"com.flowscope.xxx": "file:com.flowscope.xxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 迁移已有代码
|
||||
|
||||
如果代码已在 `Assets/` 中：
|
||||
|
||||
1. 在 `Packages/` 下建好包结构和 `package.json`
|
||||
2. 将脚本从 `Assets/` **移动**到 `Packages/com.flowscope.xxx/Runtime/`
|
||||
3. 创建 `.asmdef`（Assembly Definition），Packages 下的脚本不会自动编译到 `Assembly-CSharp.dll`
|
||||
4. Unity 重新编译，确认引用无误
|
||||
|
||||
## Assembly Definition (.asmdef)
|
||||
|
||||
Packages 下的代码必须通过 `.asmdef` 显式声明程序集。
|
||||
|
||||
**Runtime 层：**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "FlowScope.XXX.Runtime",
|
||||
"rootNamespace": "FlowScope.XXX",
|
||||
"references": [],
|
||||
"includePlatforms": [],
|
||||
"excludePlatforms": [],
|
||||
"allowUnsafeCode": false,
|
||||
"overrideReferences": false,
|
||||
"precompiledReferences": [],
|
||||
"autoReferenced": true,
|
||||
"defineConstraints": [],
|
||||
"versionDefines": [],
|
||||
"noEngineReferences": false
|
||||
}
|
||||
```
|
||||
|
||||
**Editor 层：**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "FlowScope.XXX.Editor",
|
||||
"rootNamespace": "FlowScope.XXX.Editor",
|
||||
"references": ["FlowScope.XXX.Runtime"],
|
||||
"includePlatforms": ["Editor"],
|
||||
"excludePlatforms": [],
|
||||
"allowUnsafeCode": false,
|
||||
"overrideReferences": false,
|
||||
"precompiledReferences": [],
|
||||
"autoReferenced": true,
|
||||
"defineConstraints": [],
|
||||
"versionDefines": [],
|
||||
"noEngineReferences": false
|
||||
}
|
||||
```
|
||||
|
||||
## Git 分发与版本管理
|
||||
|
||||
### 推送到 Git 仓库
|
||||
|
||||
```powershell
|
||||
cd Packages/com.flowscope.xxx
|
||||
git init
|
||||
git add .
|
||||
git commit -m "初始化 FlowScope XXX Package"
|
||||
git remote add origin https://github.com/flowscope/xxx.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### 在其他项目中引用
|
||||
|
||||
修改目标项目的 `Packages/manifest.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"com.flowscope.xxx": "https://github.com/flowscope/xxx.git"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 版本引用方式
|
||||
|
||||
| 方式 | 写法 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| 最新 main | `"https://github.com/flowscope/xxx.git"` | 内部开发 |
|
||||
| 指定版本 | `"https://github.com/flowscope/xxx.git#v1.2.0"` | 正式项目 |
|
||||
| 指定分支 | `"https://github.com/flowscope/xxx.git#dev"` | 测试分支 |
|
||||
| 指定 commit | `"https://github.com/flowscope/xxx.git#abc1234"` | 精确锁定 |
|
||||
| 本地路径 | `"file:../../com.flowscope.xxx"` | 本地联调 |
|
||||
|
||||
### 版本发布流程
|
||||
|
||||
```powershell
|
||||
# 开发完成后打 tag
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
其他项目引用指定版本：
|
||||
|
||||
```json
|
||||
"com.flowscope.xxx": "https://github.com/flowscope/xxx.git#v1.0.0"
|
||||
```
|
||||
|
||||
### 更新已安装的 Package
|
||||
|
||||
- Unity 编辑器：Window → Package Manager → 选择对应包 → 点击 Update
|
||||
- 手动：删除 `Library/PackageCache/` 中对应缓存后重启 Unity
|
||||
|
||||
## .gitignore 注意事项
|
||||
|
||||
Package 仓库的 `.gitignore`：
|
||||
|
||||
```gitignore
|
||||
# Unity 生成的 meta 文件不要忽略（Package 需要）
|
||||
# 但 Library/ 下的内容不提交
|
||||
[Ll]ibrary/
|
||||
[Tt]emp/
|
||||
[Oo]bj/
|
||||
[Bb]uild/
|
||||
[Bb]uilds/
|
||||
[Ll]ogs/
|
||||
[Uu]ser[Ss]ettings/
|
||||
|
||||
# IDE
|
||||
.vs/
|
||||
.vscode/
|
||||
.idea/
|
||||
*.csproj
|
||||
*.unityproj
|
||||
*.sln
|
||||
*.suo
|
||||
*.tmp
|
||||
*.user
|
||||
*.pidb
|
||||
*.booproj
|
||||
```
|
||||
|
||||
## FlowScope 模块化策略
|
||||
|
||||
根据 FlowScope Core Kernel 的架构原则，各模块独立为 Package：
|
||||
|
||||
```text
|
||||
FlowScope/
|
||||
├── Core/ → com.flowscope.core （纯 C#，无 Unity 依赖）
|
||||
├── UI/ → com.flowscope.ui （MVVM + uGUI 适配）
|
||||
├── Flow/ → com.flowscope.flow （时间线编排）
|
||||
├── Events/ → com.flowscope.events （事件流）
|
||||
├── Config/ → com.flowscope.config （配置加载隔离）
|
||||
├── Res/ → com.flowscope.res （资源生命周期）
|
||||
└── Modules/ → 各扩展模块
|
||||
```
|
||||
|
||||
每个模块为独立 Git 仓库，通过 `package.json` 的 `dependencies` 声明模块间依赖关系。
|
||||
Reference in New Issue
Block a user