PuerTS for Unity 安装完全指南Agent Skill 自动安装与手动 UPM 包安装详解【免费下载链接】puertsPUER(普洱) Typescript. Lets write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puertsPuerTSPUER TS是让开发者用 TypeScript 编写 Unity/UE 游戏逻辑的脚本方案。本文围绕仓库安装文档 doc/unity/zhcn/install.md 展开系统讲解面向 Unity 的两种安装路径一是通过 Agent Skill 让 AI 编码助手自动完成版本选择、依赖解析与安装二是从 Releases 下载 UPM 包手动导入。读完本文你将掌握 PuerTS 各 UPM 包之间的依赖关系、磁盘安装与 git URL 安装的具体步骤、旧版 Unity 的兼容方案以及 Windows 环境下的常见故障排查手段。一、两种安装方式怎么选PuerTS 官方提供两条安装路线适合不同场景的开发者安装方式适合人群优点注意事项Agent Skill 安装推荐使用 AI 编码助手的开发者版本选择、依赖解析、安装步骤全部由 AI 自动处理省心需要先安装 Skill 并借助支持 Agent Skill 的编码助手手动下载安装想魔改代码、不使用 AI 助手的开发者对代码魔改更友好全版本可用包多时需要逐个管理稍显繁琐如果你不确定该用哪种安装方式、该用哪个版本请先参阅 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 助手将执行的动作安装puerts v8包安装 core v8安装puerts v8包版本v3.0.1按指定版本安装 core v8安装puerts mcp包安装 core v8 nodejs mcp自动解析依赖安装puerts agent包安装 core v8 agent自动解析依赖安装puerts编辑器助手安装 agent 包和 mcp 包及其所有依赖安装puerts编辑器助手mcp版只安装 mcp 包及其依赖安装puerts lua包安装 core lua安装puerts quickjs包安装 core quickjsAI 编码助手会按照 SKILL.md 中固化的规则自动处理版本选择、依赖解析和安装步骤你无需手动下载任何文件。根据 SKILL.md 的工作流助手会依次向用户确认版本与所需包 → 依据依赖规则自动补齐依赖包并告知用户 → 检查 Release 页面可用的归档文件 → 对有原生插件的包引导下载解压、对无原生插件的包提供下载或 git URL 两种选项 → 最后通过检查Packages/manifest.json验证安装结果。三、手动下载安装全版本可用不依赖 AI 助手时可以完全手动完成安装。相比 Agent Skill 方式管理起来稍麻烦但对代码魔改更友好。3.1 下载与解压前往 PuerTS 的 Releases 页面下载你需要的包例如PuerTS_V8_x.x.x.tgz。将压缩包解压到本地任意目录解压后会得到一个标准的 UPM 包目录如v8目录内含有package.jsonUnity 正是通过该文件识别并加载包的。需要留意的是SKILL.md 明确指出Release 页面的版本号如Unity_v3.0.2以core 包的版本为基准而各个.tar.gz归档文件内部的版本号可能不同——每个包遵循各自的版本节奏。因此手动安装时应到 Release 页面的 assets 列表中确认实际可用的归档文件名。3.2 支持 UPM 的 Unity 版本Unity 2018.3通过 Unity 编辑器的 UPM 磁盘安装方式导入打开 Unity 编辑器菜单栏选择Window → Package Manager。点击左上角按钮选择Add package from disk...。在弹出的文件浏览器中导航到解压后的包目录选中其中的package.json文件点击Open。Unity 会自动识别并导入该 UPM 包。如需安装多个包如 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 目录下都有对应的源码工程。各包与仓库目录的对应关系如下归档文件Release 中的命名UPM 包名仓库目录含原生插件是否每个 Release 都有PuerTS_Core_{ver}com.tencent.puerts.coreunity/upms/core✅✅PuerTS_Lua_{ver}com.tencent.puerts.luaunity/upms/lua✅✅PuerTS_Nodejs_{ver}com.tencent.puerts.nodejsunity/upms/nodejs✅✅PuerTS_Python_{ver}com.tencent.puerts.pythonunity/upms/python✅✅PuerTS_Quickjs_{ver}com.tencent.puerts.quickjsunity/upms/quickjs✅✅PuerTS_V8_{ver}com.tencent.puerts.v8unity/upms/v8✅✅PuerTS_Webgl_{ver}com.tencent.puerts.webglunity/upms/webgl❌✅PuerTS_Agent_{ver}com.tencent.puerts.agentunity/upms/agent❌❌ 并非每个 Release 都有PuerTS_MCP_{ver}com.tencent.puerts.mcpunity/upms/mcp❌❌ 并非每个 Release 都有4.1 两个特殊包com.tencent.puerts.agent提供用于构建 LLM Agent 的 Agent 框架同时内置了基于 Agent 的 Unity 编辑器助手。com.tencent.puerts.mcp提供 MCPModel 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.corecom.tencent.puerts.agent依赖com.tencent.puerts.v8见 unity/upms/agent/package.jsoncom.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.webgl4.3 自动依赖解析示例SKILL.md 的依赖规则强调当一个包被请求安装时必须保证其所有依赖也被安装。典型解析结果如下用户请求安装必须一并安装agentcore、v8mcpcore、v8、agentmcpagentcore、v8v8coreluacore说明第二节提示词示例中安装 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带实验性功能且这些功能在未来还有可能修改或删除。RCrelease candidate版本进入 rc 后不会再激进地添加/修改/删除功能bug 量逐渐收敛一段时间无 bug 反馈后进入 release 阶段。对于追求稳定性的项目应选择 Stable 版本想尝鲜新能力则选择 Latest但要接受其潜在的变动。5.2 三种 JS 后端V8 / QuickJS / NodeJSPuerTS 本身不负责编译或解释执行 JavaScript而是引入第三方 JS 引擎来完成这件事。因此安装时选择的后端包直接决定了运行时引擎V8最经典的选择性能好、可调试、体积适中。对应com.tencent.puerts.v8包。QuickJS不支持调试和 JIT但是很小。当你有压缩安装包体积的需求时可以选择 quickjs 版本的 plugins。对应com.tencent.puerts.quickjs包。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 的版本。具体做法有两种在 Unity 编辑器中Window → Package Manager → → Add package from git URL...粘贴 URL或直接编辑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 -UseBasicParsing7.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-BitsTransferStart-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.gz7.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. Lets write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puerts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PuerTS for Unity 安装完全指南：Agent Skill 自动安装与手动 UPM 包安装详解
PuerTS for Unity 安装完全指南Agent Skill 自动安装与手动 UPM 包安装详解【免费下载链接】puertsPUER(普洱) Typescript. Lets write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puertsPuerTSPUER TS是让开发者用 TypeScript 编写 Unity/UE 游戏逻辑的脚本方案。本文围绕仓库安装文档 doc/unity/zhcn/install.md 展开系统讲解面向 Unity 的两种安装路径一是通过 Agent Skill 让 AI 编码助手自动完成版本选择、依赖解析与安装二是从 Releases 下载 UPM 包手动导入。读完本文你将掌握 PuerTS 各 UPM 包之间的依赖关系、磁盘安装与 git URL 安装的具体步骤、旧版 Unity 的兼容方案以及 Windows 环境下的常见故障排查手段。一、两种安装方式怎么选PuerTS 官方提供两条安装路线适合不同场景的开发者安装方式适合人群优点注意事项Agent Skill 安装推荐使用 AI 编码助手的开发者版本选择、依赖解析、安装步骤全部由 AI 自动处理省心需要先安装 Skill 并借助支持 Agent Skill 的编码助手手动下载安装想魔改代码、不使用 AI 助手的开发者对代码魔改更友好全版本可用包多时需要逐个管理稍显繁琐如果你不确定该用哪种安装方式、该用哪个版本请先参阅 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 助手将执行的动作安装puerts v8包安装 core v8安装puerts v8包版本v3.0.1按指定版本安装 core v8安装puerts mcp包安装 core v8 nodejs mcp自动解析依赖安装puerts agent包安装 core v8 agent自动解析依赖安装puerts编辑器助手安装 agent 包和 mcp 包及其所有依赖安装puerts编辑器助手mcp版只安装 mcp 包及其依赖安装puerts lua包安装 core lua安装puerts quickjs包安装 core quickjsAI 编码助手会按照 SKILL.md 中固化的规则自动处理版本选择、依赖解析和安装步骤你无需手动下载任何文件。根据 SKILL.md 的工作流助手会依次向用户确认版本与所需包 → 依据依赖规则自动补齐依赖包并告知用户 → 检查 Release 页面可用的归档文件 → 对有原生插件的包引导下载解压、对无原生插件的包提供下载或 git URL 两种选项 → 最后通过检查Packages/manifest.json验证安装结果。三、手动下载安装全版本可用不依赖 AI 助手时可以完全手动完成安装。相比 Agent Skill 方式管理起来稍麻烦但对代码魔改更友好。3.1 下载与解压前往 PuerTS 的 Releases 页面下载你需要的包例如PuerTS_V8_x.x.x.tgz。将压缩包解压到本地任意目录解压后会得到一个标准的 UPM 包目录如v8目录内含有package.jsonUnity 正是通过该文件识别并加载包的。需要留意的是SKILL.md 明确指出Release 页面的版本号如Unity_v3.0.2以core 包的版本为基准而各个.tar.gz归档文件内部的版本号可能不同——每个包遵循各自的版本节奏。因此手动安装时应到 Release 页面的 assets 列表中确认实际可用的归档文件名。3.2 支持 UPM 的 Unity 版本Unity 2018.3通过 Unity 编辑器的 UPM 磁盘安装方式导入打开 Unity 编辑器菜单栏选择Window → Package Manager。点击左上角按钮选择Add package from disk...。在弹出的文件浏览器中导航到解压后的包目录选中其中的package.json文件点击Open。Unity 会自动识别并导入该 UPM 包。如需安装多个包如 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 目录下都有对应的源码工程。各包与仓库目录的对应关系如下归档文件Release 中的命名UPM 包名仓库目录含原生插件是否每个 Release 都有PuerTS_Core_{ver}com.tencent.puerts.coreunity/upms/core✅✅PuerTS_Lua_{ver}com.tencent.puerts.luaunity/upms/lua✅✅PuerTS_Nodejs_{ver}com.tencent.puerts.nodejsunity/upms/nodejs✅✅PuerTS_Python_{ver}com.tencent.puerts.pythonunity/upms/python✅✅PuerTS_Quickjs_{ver}com.tencent.puerts.quickjsunity/upms/quickjs✅✅PuerTS_V8_{ver}com.tencent.puerts.v8unity/upms/v8✅✅PuerTS_Webgl_{ver}com.tencent.puerts.webglunity/upms/webgl❌✅PuerTS_Agent_{ver}com.tencent.puerts.agentunity/upms/agent❌❌ 并非每个 Release 都有PuerTS_MCP_{ver}com.tencent.puerts.mcpunity/upms/mcp❌❌ 并非每个 Release 都有4.1 两个特殊包com.tencent.puerts.agent提供用于构建 LLM Agent 的 Agent 框架同时内置了基于 Agent 的 Unity 编辑器助手。com.tencent.puerts.mcp提供 MCPModel 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.corecom.tencent.puerts.agent依赖com.tencent.puerts.v8见 unity/upms/agent/package.jsoncom.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.webgl4.3 自动依赖解析示例SKILL.md 的依赖规则强调当一个包被请求安装时必须保证其所有依赖也被安装。典型解析结果如下用户请求安装必须一并安装agentcore、v8mcpcore、v8、agentmcpagentcore、v8v8coreluacore说明第二节提示词示例中安装 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带实验性功能且这些功能在未来还有可能修改或删除。RCrelease candidate版本进入 rc 后不会再激进地添加/修改/删除功能bug 量逐渐收敛一段时间无 bug 反馈后进入 release 阶段。对于追求稳定性的项目应选择 Stable 版本想尝鲜新能力则选择 Latest但要接受其潜在的变动。5.2 三种 JS 后端V8 / QuickJS / NodeJSPuerTS 本身不负责编译或解释执行 JavaScript而是引入第三方 JS 引擎来完成这件事。因此安装时选择的后端包直接决定了运行时引擎V8最经典的选择性能好、可调试、体积适中。对应com.tencent.puerts.v8包。QuickJS不支持调试和 JIT但是很小。当你有压缩安装包体积的需求时可以选择 quickjs 版本的 plugins。对应com.tencent.puerts.quickjs包。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 的版本。具体做法有两种在 Unity 编辑器中Window → Package Manager → → Add package from git URL...粘贴 URL或直接编辑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 -UseBasicParsing7.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-BitsTransferStart-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.gz7.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. Lets write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puerts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考