FlowScope/docs/guide/unity-package-git-workflow.md

Unity Package 开发与 Git 分发指南

概述

本文档描述如何将 Unity 代码组织为 Package 结构，并通过 Git 仓库进行版本管理和分发更新。适用于 FlowScope 框架各模块的独立开发与集成。

Package 标准结构

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 说明

{
  "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/ 中写脚本一致。

MyUnityProject/
├── Assets/
│   └── Scenes/
│       └── Test.unity          # 测试场景
├── Packages/
│   ├── manifest.json
│   └── com.flowscope.xxx/      ← 在这里开发
│       ├── package.json
│       ├── Runtime/
│       └── Editor/

manifest.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 层：

{
  "name": "FlowScope.XXX.Runtime",
  "rootNamespace": "FlowScope.XXX",
  "references": [],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": true,
  "defineConstraints": [],
  "versionDefines": [],
  "noEngineReferences": false
}

Editor 层：

{
  "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 仓库

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：

{
  "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"	本地联调

版本发布流程

# 开发完成后打 tag
git tag v1.0.0
git push origin v1.0.0

其他项目引用指定版本：

"com.flowscope.xxx": "https://github.com/flowscope/xxx.git#v1.0.0"

更新已安装的 Package

• Unity 编辑器：Window → Package Manager → 选择对应包 → 点击 Update
• 手动：删除 Library/PackageCache/ 中对应缓存后重启 Unity

.gitignore 注意事项

Package 仓库的 .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：

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 声明模块间依赖关系。