企业官网建设流程全解析

PuerTS for Unity 安装完全指南：Agent Skill 自动安装与手动 UPM 包安装详解

【免费下载链接】puertsPUER(普洱) Typescript. Let's write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puerts

PuerTS（PUER TS）是让开发者用 TypeScript 编写 Unity/UE 游戏逻辑的脚本方案。本文围绕仓库安装文档 doc/unity/zhcn/install.md 展开，系统讲解面向 Unity 的两种安装路径：一是通过 Agent Skill 让 AI 编码助手自动完成版本选择、依赖解析与安装；二是从 Releases 下载 UPM 包手动导入。读完本文，你将掌握 PuerTS 各 UPM 包之间的依赖关系、磁盘安装与 git URL 安装的具体步骤、旧版 Unity 的兼容方案，以及 Windows 环境下的常见故障排查手段。

一、两种安装方式：怎么选

PuerTS 官方提供两条安装路线，适合不同场景的开发者：

如果你不确定该用哪种安装方式、该用哪个版本，请先参阅 FAQ 的"安装相关"章节，里面详细解释了 Stable/Latest/RC/Preview 版本含义、三种 JS 后端的区别，以及 OpenUPM / Git Clone / 拷贝安装三条路线的取舍。

二、通过 Agent Skill 安装（推荐）

PuerTS 在仓库中内置了一个名为install-puerts-for-unity的 Agent Skill，其完整定义位于 unity/skills/install-puerts-for-unity/SKILL.md。安装该 Skill 后，你可以用自然语言提示词让 AI 编码助手帮你完成安装。

支持 Agent Skill 的常见 AI 编码助手包括：CodeBuddy、Claude Code、Cursor、Windsurf、Cline、GitHub Copilot 等。

Skill 路径：puerts/unity/skills/install-puerts-for-unity（即仓库中的 unity/skills/install-puerts-for-unity 目录）

常用示例提示词

AI 编码助手会按照 SKILL.md 中固化的规则自动处理版本选择、依赖解析和安装步骤，你无需手动下载任何文件。根据 SKILL.md 的工作流，助手会依次：向用户确认版本与所需包 → 依据依赖规则自动补齐依赖包并告知用户 → 检查 Release 页面可用的归档文件 → 对有原生插件的包引导下载解压、对无原生插件的包提供下载或 git URL 两种选项 → 最后通过检查Packages/manifest.json验证安装结果。

三、手动下载安装（全版本可用）

不依赖 AI 助手时，可以完全手动完成安装。相比 Agent Skill 方式管理起来稍麻烦，但对代码魔改更友好。

3.1 下载与解压

1. 前往 PuerTS 的 Releases 页面下载你需要的包，例如PuerTS_V8_x.x.x.tgz。
2. 将压缩包解压到本地任意目录，解压后会得到一个标准的 UPM 包目录（如v8），目录内含有package.json，Unity 正是通过该文件识别并加载包的。

需要留意的是，SKILL.md 明确指出：Release 页面的版本号（如Unity_v3.0.2）以core 包的版本为基准，而各个.tar.gz归档文件内部的版本号可能不同——每个包遵循各自的版本节奏。因此手动安装时，应到 Release 页面的 assets 列表中确认实际可用的归档文件名。

3.2 支持 UPM 的 Unity 版本（Unity 2018.3+）

通过 Unity 编辑器的 UPM 磁盘安装方式导入：

1. 打开 Unity 编辑器，菜单栏选择Window → Package Manager。
2. 点击左上角＋按钮，选择Add package from disk...。
3. 在弹出的文件浏览器中，导航到解压后的包目录，选中其中的package.json文件，点击Open。
4. Unity 会自动识别并导入该 UPM 包。
5. 如需安装多个包（如 core + v8），对每个包重复上述步骤。

由于com.tencent.puerts.core是基础包，其他所有包都依赖它，手动安装时务必先保证 core 包已就位（详见下文第四节）。

3.3 不支持 UPM 的 Unity 版本（Unity 2018.3 以下）

将解压后的文件夹直接拷贝到项目的Assets目录下。

⚠️ 注意：还需要将 PuerTS 代码内的内置 js 文件手动加上.txt后缀，否则这些文件可能不会被 Unity 正确打包或识别。

macOS 提示：mac 下如果遇到"移入废纸篓"问题，请使用sudo xattr -r -d com.apple.quarantine puerts.bundle清除隔离属性。但这样做之后提交 git 容易出问题，请自行权衡。

四、理解包结构与依赖关系

PuerTS 将功能拆分为多个独立 UPM 包，每个包在仓库的 unity/upms 目录下都有对应的源码工程。各包与仓库目录的对应关系如下：

4.1 两个特殊包

• com.tencent.puerts.agent：提供用于构建 LLM Agent 的 Agent 框架，同时内置了基于 Agent 的 Unity 编辑器助手。
• com.tencent.puerts.mcp：提供 MCP（Model Context Protocol）框架，并内置基于 MCP 的编辑器助手。从 unity/upms/mcp/package.json 的描述可见，它是一个"为外部 Agent 暴露 evalJsCode 工具的 MCP Server，由 PuerTS Node.js 后端驱动"。

4.2 依赖关系（以 package.json 声明为准）

从仓库中各包的 package.json 依赖声明可以精确还原依赖链：

• com.tencent.puerts.core是基础包，不依赖任何其他 PuerTS 包，但所有其他包都依赖它（v8、lua、nodejs、python、quickjs、webgl 均声明依赖com.tencent.puerts.core）；
• com.tencent.puerts.agent依赖com.tencent.puerts.v8（见 unity/upms/agent/package.json）；
• com.tencent.puerts.mcp依赖com.tencent.puerts.v8与com.tencent.puerts.agent（见 unity/upms/mcp/package.json）。

依赖图可以整理为：

com.tencent.puerts.core （所有包的公共基础） ├── com.tencent.puerts.v8 │ ├── com.tencent.puerts.agent │ │ └── com.tencent.puerts.mcp │ └── com.tencent.puerts.mcp ├── com.tencent.puerts.nodejs ├── com.tencent.puerts.lua ├── com.tencent.puerts.python ├── com.tencent.puerts.quickjs └── com.tencent.puerts.webgl

4.3 自动依赖解析示例

SKILL.md 的依赖规则强调：当一个包被请求安装时，必须保证其所有依赖也被安装。典型解析结果如下：

说明：第二节提示词示例中"安装 mcp 包"被解析为 core + v8 + nodejs + mcp，这与 mcp 包"由 PuerTS Node.js 后端驱动"的描述相吻合；而包声明层面的直接依赖以 unity/upms/mcp/package.json 为准（v8 + agent）。两种口径的结合点在于：安装 mcp 时既需要满足声明依赖，也可能需要 Node.js 后端来支撑其运行时能力，具体以你安装时 AI 助手解析出的完整清单为准。

五、版本选择与后端选择

在动手安装前，建议先明确两个问题：用哪个版本、用哪种 JS 后端。这两点在 FAQ 的"安装相关"章节中有详细说明，摘其要点如下。

5.1 Stable / Latest / RC / Preview 怎么选

• Stable：该版本已经过长久验证，可以稳定使用，基本不会有明显问题。
• Latest：搭载最新功能，例如兼容近期上下游变更（如 Mac M 系列 CPU 的推出），或包含更高性能的调用、更平滑的入门曲线等。
• Preview / pre：带实验性功能，且这些功能在未来还有可能修改或删除。
• RC（release candidate）：版本进入 rc 后不会再激进地添加/修改/删除功能，bug 量逐渐收敛，一段时间无 bug 反馈后进入 release 阶段。

对于追求稳定性的项目，应选择 Stable 版本；想尝鲜新能力则选择 Latest，但要接受其潜在的变动。

5.2 三种 JS 后端：V8 / QuickJS / NodeJS

PuerTS 本身不负责编译或解释执行 JavaScript，而是引入第三方 JS 引擎来完成这件事。因此安装时选择的"后端包"直接决定了运行时引擎：

1. V8：最经典的选择，性能好、可调试、体积适中。对应com.tencent.puerts.v8包。
2. QuickJS：不支持调试和 JIT，但是很小。当你有压缩安装包体积的需求时，可以选择 quickjs 版本的 plugins。对应com.tencent.puerts.quickjs包。
3. NodeJS：是 OpenUPM 版本所使用的后端。它在 V8 的基础上提供了文件、网络等 API，支撑了 JavaScript 生态的大半江山，使用它你可以更顺畅地使用 npm 带来的各种包。对应com.tencent.puerts.nodejs包。

工程结构提示：选择不同后端后，原生插件会落在对应包的 Plugins 目录下。以仓库结构为例，unity/upms/v8/Plugins 下按 Android、iOS、macOS、OpenHarmony、x86_64 等平台组织原生二进制；unity/upms/core/Plugins 则包含 Android、WebGL、iOS、macOS、x86_64 等平台的公共插件。手动安装或排查缺失原生库问题时，可按平台目录核对。

六、验证安装

安装完成后，可打开项目的Packages/manifest.json，检查是否出现了预期的包条目：

• com.tencent.puerts.core
• 至少一个后端包：com.tencent.puerts.v8（或com.tencent.puerts.lua、com.tencent.puerts.nodejs、com.tencent.puerts.python、com.tencent.puerts.quickjs）
• 按需出现：com.tencent.puerts.agent、com.tencent.puerts.webgl、com.tencent.puerts.mcp

本地包必须使用file:前缀

如果你将解压后的包目录放入了项目的Packages/目录（SKILL.md 推荐的下载解压式安装），manifest.json必须以file:前缀引用这些本地路径，例如：

{ "dependencies": { "com.tencent.puerts.core": "file:core", "com.tencent.puerts.v8": "file:v8", "com.tencent.puerts.nodejs": "file:nodejs", "com.tencent.puerts.agent": "file:agent", "com.tencent.puerts.mcp": "file:mcp" } }

Unity 会在打开项目时自动解析这些本地路径。

git URL 安装方式

对于无原生插件的包（webgl、agent、mcp），除了下载解压，还可以用 Unity 的Add package from git URL功能直接安装。URL 指向仓库unity/upms/下的对应包目录，并可附带 Release tag 固定版本；当 Release 页面不存在对应归档时（如agent、mcp并非每个 Release 都有），可使用不带 tag 的版本。具体做法有两种：

1. 在 Unity 编辑器中：Window → Package Manager → + → Add package from git URL...粘贴 URL；
2. 或直接编辑Packages/manifest.json的"dependencies"字段，例如：

{ "dependencies": { "com.tencent.puerts.agent": "git url，指向 unity/upms/agent 子目录并带 Unity_v3.0.2 tag" } }

七、Windows 下的常见问题与故障排查

SKILL.md 针对 Windows 环境整理了若干真实踩坑点，手动安装或编写自动化脚本时非常值得参考。

7.1curl在 PowerShell 中是Invoke-WebRequest的别名

Windows PowerShell 中curl实际是Invoke-WebRequest的别名，不接受Unix curl 的-L、--max-time、-o等参数。应改用 PowerShell 原生语法：

# ❌ 错误：Unix curl 参数在 PowerShell 中不可用 curl -L --max-time 30 -o output.html https://... # ✅ 正确：使用 Invoke-WebRequest 与 PowerShell 参数 Invoke-WebRequest -Uri "https://..." -OutFile "output.html" -UseBasicParsing

7.2 GitHub API 未认证时容易触发限流

直接调用 Releases API 查询归档列表，未认证状态下很快会触发 GitHub 的 rate limit（尤其是在共享 IP 上）。替代方案：不要走 API，而是抓取expanded_assets的静态 HTML 片段，它包含全部下载链接且不受限流影响：

Invoke-WebRequest -Uri "https://github.com/Tencent/puerts/releases/expanded_assets/Unity_v{VERSION}" ` -OutFile "assets.html" -UseBasicParsing # 用正则提取下载链接 $content = Get-Content "assets.html" -Raw $matches = [regex]::Matches($content, 'href="(/Tencent/puerts/releases/download[^"]*)"') $matches | ForEach-Object { $_.Groups[1].Value }

这样可以拿到确切的归档文件名（例如PuerTS_Core_3.0.2.tar.gz），且不消耗 API 配额。

7.3 大文件下载超时

Invoke-WebRequest下载大包时容易超时（例如PuerTS_V8约 74 MB、PuerTS_Nodejs约 169 MB）。替代方案：使用更可靠且不会超时的Start-BitsTransfer：

Start-BitsTransfer ` -Source "https://github.com/Tencent/puerts/releases/download/Unity_v3.0.2/PuerTS_V8_3.0.2.tar.gz" ` -Destination "C:\path\to\output\PuerTS_V8_3.0.2.tar.gz"

7.4 Release 页面 HTML 中没有下载链接

Release 主页面（/releases/tag/Unity_v{VERSION}）的资产链接由 JavaScript 动态渲染，用Invoke-WebRequest抓到的原始 HTML不包含任何releases/download链接。解决方案：改用 7.2 节介绍的expanded_assets端点，它返回包含全部资产链接的静态 HTML 片段。

八、安装后：下一步可以做什么

安装完成后，你可以参考 安装文档的同级指南 解决常见报错（例如"invalid arguments to XXX"这类 TypeScript 重载选择问题、setInterval无回调需要调用JsEnv.Tick等运行时问题）。PuerTS 的 Unity 文档目录还包含 JS 与 C# 互调教程、TypeScript 使用说明、调试指南 等资料，安装完成后可进一步深入。

核心要点回顾：无论走 Agent Skill 还是手动路线，"core 包是所有包的公共基础"这条依赖铁律贯穿始终；选择后端包即选择运行时引擎（V8/QuickJS/NodeJS）；含原生插件的 6 个包必须下载解压安装，无原生插件的 3 个包（webgl/agent/mcp）则可用 git URL 方式；最后务必通过Packages/manifest.json核验安装结果，本地包记得使用file:前缀。

【免费下载链接】puertsPUER(普洱) Typescript. Let's write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puerts