一个 **协程** 用于在同一个脚本内同时执行多个任务。这些任务可能包括从输入中生成值或在解决更大问题时在子例程上执行工作。一个任务甚至不需要有一个明确的结束点，但它确实需要定义特定的时间，在这些时间它 **让出**（暂停）以让其他事情可以执行。

## 使用协程

可以通过向 `Library.coroutine.create()` 提供一个函数来创建一个新的协程。一旦创建，协程不会开始运行，直到第一次调用 `Library.coroutine.resume()` 并传递函数的参数。此调用在函数停止或调用 `Library.coroutine.yield()` 时返回，并且在这种情况下， `Library.coroutine.resume()` 返回函数返回的值、发送到 `Library.coroutine.yield()` 的值或错误信息。如果发生错误，第二个返回值是抛出的错误。

```lua
local function task(...)
	-- 这个函数可能稍微做一些工作然后让出一些值
	coroutine.yield("first")  -- 由 coroutine.resume() 返回
	-- 函数在再次恢复时继续执行
	return "second"
end

local taskCoro = coroutine.create(task)
-- 第一次调用 resume，执行函数从头开始运行
local success, result = coroutine.resume(taskCoro, ...)
print(success, result)  --> true, first (任务调用了 coroutine.yield())
-- 继续运行这个函数，直到它让出或停止
success, result = coroutine.resume(taskCoro)
print(success, result)  --> true, second (任务因为返回了 "second" 而停止)
```

在协程的生命周期内，可以调用 `Library.coroutine.status()` 来检查其状态：

<table>
    <thead>
        <tr>
            <th>状态</th>
            <th>含义</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><b>挂起</b></td> <td>协程在等待被恢复。协程开始于这种状态，并在其函数调用 <code>coroutine.yield()</code> 时进入此状态。</td>
        </tr>
        <tr>
            <td><b>运行</b></td>
            <td>协程现在正在运行。</td>
        </tr>
        <tr>
            <td><b>正常</b></td> <td>协程在等待另一个协程的让出；换句话说，它已恢复另一个协程。</td>
        </tr>
        <tr>
            <td><b>死亡</b></td> <td>函数已经停止（返回或抛出错误）。协程不能再使用。</td>
        </tr>
    </tbody>
</table>

### 包装协程

在处理协程时，您还可以放弃使用协程对象，而是使用包装函数。这样的包装函数将在调用时恢复特定的协程，并仅返回已让出的值。您可以使用 `Library.coroutine.wrap()` 来实现：

```lua
-- 创建协程并返回一个每次调用时恢复它的包装函数
local f = coroutine.wrap(task)
-- 像调用 coroutine.resume() 一样恢复协程
local result = f()
-- 如果发生错误，将在此处引发！
-- 这与 coroutine.resume() 不同，后者的行为类似于 pcall()
```

从 `Library.coroutine.resume()` 返回的第一个值描述了协程是否没有错误地运行。然而，`Library.coroutine.wrap()` 返回的函数不会这样做：相反，它们直接返回返回或传递给 `Library.coroutine.yield()` 的值（如果有的话）。如果在运行协程函数时发生错误，则在调用返回的函数时引发错误。

### 生产者模式示例

想象一个任务，它生成一个单词的重复：每次生成一个重复，下一次将产生更多。例如，提供 `Hello` 将生成 `Hello`、`HelloHello`、`HelloHelloHello` 等。要实现这一点，可以定义 `repeatThis()`：

```lua
-- 这个函数每次其协程被恢复时重复一个单词
local function repeatThis(word)
	local repetition = ""
	while true do
		-- 做一次重复然后让出结果
		repetition = repetition .. word
		coroutine.yield(repetition)
	end
end
```

要将此函数作为协程运行，可以使用 `Library.coroutine.create()` 并随后多次调用 `Library.coroutine.resume()`：

```lua
local repetitionCoro = coroutine.create(repeatThis)
print(coroutine.resume(repetitionCoro, "Hello"))  -- true, Hello
print(coroutine.resume(repetitionCoro))           -- true, HelloHello
print(coroutine.resume(repetitionCoro))           -- true, HelloHelloHello
```

对于这个生产者函数，您还可以使用 `Library.coroutine.wrap()` 获取一个生成值的函数：

```lua
local f = coroutine.wrap(repeatThis)
print(f("Hello"))  -- Hello
print(f())         -- HelloHello
print(f())         -- HelloHelloHello
```

关闭并将提供的协程置于死亡状态。此函数返回 `true`，除非协程处于错误状态，在这种情况下返回 `false` 和错误信息。当前正在运行的协程无法被关闭。协程关闭后不能恢复。

coroutine.close

`true`，前提是要关闭的协程不处于错误状态。

关闭并将提供的协程置于死亡状态。

创建一个新的协程，主体为 f。 f 必须是一个 Luau 函数。

coroutine.create

如果此函数被调用的协程可以安全地让出，则返回 `true`。在元方法或 C 函数内部让出协程是被禁止的，`pcall` 和 `xpcall` 是例外。

coroutine.isyieldable

协程在此时是否可以安全地让出。

如果此函数被调用的协程可以安全地让出，则返回 `true`。

启动或继续协程 `co` 的执行。首次恢复协程时，它开始运行其主体。值 `...` 作为参数传递给主体函数。如果协程已让出，则恢复它；值 `...` 作为让出的结果传递。如果协程没有任何错误地运行，则恢复返回 true 加上传递给让出的任何值（如果协程让出）或主体函数返回的任何值（如果协程终止）。如果有任何错误，恢复返回 false 加上错误信息。

coroutine.resume

coroutine.running

返回协程 co 的状态，作为字符串：'running'，如果协程正在运行（即调用了状态）；'suspended'，如果协程在让出的调用中被挂起，或者如果它尚未开始运行；'normal' 如果协程处于活动状态但未运行（即，它已恢复另一个协程）；如果协程已完成其主体函数，或者如果它在错误中停止，则为'dead'。

coroutine.status

以字符串形式返回协程 co 的状态。

创建一个新的协程，主体为 f。 f 必须是一个 Luau 函数。返回一个每次被调用时恢复协程的函数。传递给该函数的任何参数都作为额外参数传递给恢复。返回与恢复相同的值，除了第一个布尔值。发生错误时，错误将会被传播。

coroutine.wrap

创建一个新的协程并返回一个每次调用时恢复该协程的函数。

暂停调用协程的执行。向让出提供的任何参数将作为额外结果传递给恢复。在元方法或 C 函数中让出协程是被禁止的，`pcall` 和 `xpcall` 是例外。

coroutine.yield

coroutine

一个与主线程同时执行的函数。

/reference/engine/libraries/coroutine.yaml

一个在特定事件发生时运行连接的函数的对象。

Data Type

RBXScriptSignal

Luau

Tuple

Variant

boolean

函数是可以按命令多次执行的代码块。

function

一系列字符，如字母、数字和符号。

string

Library

体验

虚拟形象

素材

范例和项目

引擎 API

Open Cloud API

Studio

分析

平台

教程

创作者计划

教育

课程

学习

此方法是异步的，会返回一个`Operation`对象，该对象表示操作的当前状态。它包含一个端点路径，您可以轮询该路径以获取实际响应和相关的元数据。有关长时间运行操作的更多信息，请参阅[文档]({longRunningOperationsLink})。

以下部分描述了操作完成时提供的响应和元数据对象。

Beta 测试终点已准备好公开使用。可能出现导致功能无法正常运作的更改，但几率极低。

这些 Open Cloud 文档页面将于 2026 年 3 月 31 日移除。届时你将被自动重定向到新的 Open Cloud 文档。{linkStart}了解更多{linkEnd}

这些旧 Open Cloud 页面将于 2026 年 3 月 31 日移除并重定向。{linkStart}了解更多{linkEnd}

实验性终端节点已准备好供公众使用，但随着 API 协定的最终确定，可能偶尔会出现重大变更。

此终端节点可通过使用 API 密钥的 {httpServiceLinkStart}HttpService{httpServiceLinkEnd} 在体验中调用。

此字段可能在创建资源时被设置，但可能无法在后续请求中修改。

这些字段可能在创建资源时被设置，但可能无法在后续请求中修改。

此字段可以在请求中提供，但永远不会包括在答复中。

旧版验证方法。始终首选使用 API 密钥或 OAuth 2.0（如有）。

每个 API 密钥：每个 IP 地址每 {periodInSeconds} 秒有 {maxInPeriod} 次请求

无需身份验证即可调用。通常会显著降低速率限制。始终首选使用 API 密钥或 OAuth 2.0（如有）。

对于每个分组，只需提供架构中的以下字段之一，其余字段可以排除。

你可以随时重新选择加入。{linkStart}提供反馈。{linkEnd}

你正在查看旧版文档。{linkStart}提供反馈。{linkEnd}

你可以随时退出，并重定向回旧的引用页面。{linkStart}在这里提供反馈。{linkEnd}

你正在查看全新改版的文档。{linkStart}提供反馈。{linkEnd}

此字段可能被设置为响应，但在请求中将被忽略。

注意：在高流量期间，速率限制可能会更低。某些终端节点有额外的速率限制。[进一步了解速率限制]({link})。

用户或群组所有 API 密钥每天 {limit} 个请求

用户或群组所有 API 密钥每小时 {limit} 个请求

用户或群组所有 API 密钥每分钟 {limit} 个请求

用户或群组所有 API 密钥每秒 {limit} 个请求

每个 API 密钥所有者每分钟 {limit} 个请求

每个 App 用户每天 {limit} 个请求

每个 App 用户每小时 {limit} 个请求

每个 App 用户每分钟 {limit} 个请求

每个 App 用户每秒 {limit} 个请求

每个 API 密钥所有者每秒 {limit} 个请求

范围可以控制你的凭据拥有哪些权限。你的凭据只能访问你所选范围支持的终端节点。

稳定终端节点已准备好投入生产使用，在其生命周期内几乎不会发生重大变更。

此目标允许你将密钥的访问权限限制为选定的{requiredParts}

此目标允许你将密钥的访问权限限制为选定的{requiredParts}和{optionalParts}

目标类型用于限制你的凭据可操作的资源。即使你的帐户拥有其他资源的权限，也只能处理选定的资源。某些范围没有目标部件，在这种情况下，你的所有相关资源都可进行操作。

对于用户拥有的 API 密钥，无需选择宇宙顶级部件。在这种情况下，你的 API 密钥可以访问你拥有的所有个人体验，以及你在群组中拥有相应权限的群组体验。

尚不支持试用需要 API 密钥或 OAuth 2.0 验证的终端节点

为了安全起见，已停用高风险操作的 Cookie 验证。

关键风险终端节点非常敏感，为了安全起见，已停用“试用”

注意：此代码示例中不包含验证标头。你可能需要添加验证标头，以便此命令能够正常运作。

这是会修改或删除关键数据的高风险终端节点。测试时要格外小心。

此 API 终端节点已被归类为高风险，可能会影响实时数据或用户帐户。

对高风险 API 的已验证请求可能会进行无法撤销的更改。请在继续之前仔细查看你的请求参数。

这是会取回数据的低风险终端节点。通常可以安全测试。

这是会修改数据的中风险终端节点。请使用非关键帐户仔细测试，因为更改可能是永久性的。

为了确保你帐户的安全，请不要在此处粘贴来自其他来源的文本，或将此页面的信息发送给其他人。

你即将使用实际帐户凭据测试实时 API 终端节点。

只有在你了解即将进行的 API 调用的影响后才能继续。在测试之前，请仔细查看 API 文档。

将使用已验证的会话进行 API 调用

这些是可能影响你帐户或数据的真实 API 调用

某些操作可能会修改或删除数据

此终端节点已被以下推荐的替代终端节点取代：

调用此终端节点需要以下范围。如需
有关生成正确密钥的更多信息，请参阅 [管理 API 密钥]({apiKeyReferenceDocLink})。

如需有关生成密钥的更多信息，请参阅 [管理 API 密钥]({apiKeyReferenceDocLink})。

相对于基础 URL 的路径，下列端点是可用的。

此字符串格式为 [FieldMask](/cloud/reference/types#fieldmask)。

JSON 值可以是 “null”、“boolean”、“string”、“number”、“array” 或 “object”。

你的 OAuth 2.0 应用程序需要以下范围才能使用此终端节点。如需进一步了解如何注册 OAuth 2.0 应用程序，请参阅 [App 注册和审核]({oauth2ReferenceDocLink})。

如需进一步了解如何注册 OAuth 2.0 应用程序，请参阅 [App 注册和审核]({oauth2ReferenceDocLink})。

下列对象描述了接受或返回的有效载荷。请参阅每个单独的端点，以了解更多关于这些对象用途的信息。

调用此终端节点需要以下范围。

资源路径

若要使用此端点，你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息，请查看【应用程序注册及评价】({oauth2ReferenceDocLink})。

不推荐

你正在查看更新后的 Open Cloud 引用。

你已退出新的 Open Cloud 引用。

创建、更新和管理你的广告活动。

这将允许查看关于你素材的信息。

这将允许在 Roblox 上传或更新素材。

允许查看你的帐户有权访问的主体（包括群组和体验）和素材。

这将允许向你帐户有权访问的任何主体（包括群组和体验）和素材授予素材权限。

允许代表你查看虚拟形象自动设置任务的状态和结果。

允许代表你创建和管理虚拟形象自动设置任务。

授予更新用户拥有的徽章的能力。

这将允许查看有关你商业项目的信息。

这将允许更改你的同步商业项目。

这将允许查看有关你商户联结平台的信息。

这将允许编辑你的商户联结平台。

这将允许你查看关于你创作者商店产品的信息。

这将允许你修改关于你创作者商店产品的信息。

这将允许你查看关于你创作者商店保存的信息。

这将允许你修改关于你创作者商店保存的信息。

授予代表你创建数据存储的权限。

授予代表你删除数据存储的权限。

授予读取数据存储列表的权限。

授予拍摄数据存储快照的权限。

授予在数据存储中创建条目的权限。

授予标记要删除的指定条目的权限。

授予列出数据存储条目的权限。

授予读取数据存储中指定条目的权限。

授予更新条目的值、属性和用户的权限。

授予删除数据存储条目修订的权限。

授予列出数据存储条目修订的权限。

授予读取数据存储条目修订的权限。

授予查看授权用户的开发者产品配置详细信息的权限。

授予编辑授权用户的开发者产品的权限。

这将允许查看有关你宇宙环境的信息。

授予查看授权用户的游戏通行证配置详细信息的权限。

授予编辑授权用户的游戏通行证的权限。

授予查看你的帐户社区论坛信息的权限。

授予访问权限，允许管理你的帐户对应的社区论坛信息。

这将允许查看有关你社区的信息。

这将允许你管理社区加入请求，并处理你帐户中低级别社区成员的角色更新。

允许你修改实例的属性数据（目前仅支持脚本）。

这将允许查看你的道具栏信息。

授予权限，以管理你的徽章并使用 Robux。

授予更新授权用户徽章的权限。

授予读取你已开启通知的体验信息的权限。

授予代表你开启或关闭体验通知的权限。

授予读取和写入本地化表格的权限

授予为你拥有的所有体验管理团队协作的权限。

授予管理体验和与体验相关的某些信息（例如本地化信息）的权限。

授予读取体验本地化信息的权限。

授予修改体验本地化偏好设置的权限。

授予修改用户本地化偏好设置的权限。

允许你查看关联场景的 Luau 执行任务的状态、日志和结果。

允许你为关联场景创建新的 Luau 执行任务。

授予异步清空宇宙中所有数据结构的权限。

授予从队列前端丢弃已读项目的权限。

授予读取队列前端项目的权限。

授予读取记忆存储项目的权限。

授予创建、更新和删除地图项目的权限。

授予代替用户发布信息的权力。

这将允许从你的体验向用户发送通知。

（已弃用）授予读取有序数据存储中条目列表的权限。

（已弃用）授予在有序数据存储中创建新条目的权限。

授予从有序数据存储中列出条目的权限。

授予在有序数据存储中创建条目的权限。

这将允许列出与你的作品相关联的密钥。

这将允许创作和更新与你的作品相关联的密钥。

此权限允许你提交评估工作并查看工作结果。

授予读取订阅产品信息的权限。

授予在 Roblox 上发布新版本体验的权限。

授予编辑授权用户体验的权限。

允许你查看体验中的用户限制。

允许你编辑体验中的用户限制。

允许查看发送至你帐户的通知。

授予读取用户 Premium 和验证状态的能力。

这将允许你查看授权用户的社交帐户。

这将授予读取你的个人资料信息的权限。

此函数将在可能是立即返回，但在返回值之前可以暂停调用自己的线程。

了解更多关于{linkStart}功能{linkEnd}的信息。

Roblox 已不再支持或维护{nameStart}名称{nameEnd}。

Roblox 不再支持或维护此终端节点。

Roblox 已不再支持或维护这项数学运算。

此成员未在对象浏览器中出现，不应广泛使用。

此成员只能通过命令行访问。从脚本尝试访问此成员将导致错误。

此函数无法暂停调用自己的 Lua 线程。

从脚本尝试访问此成员将导致错误。你可能可以从 Roblox Studio 的属性窗口访问。

此成员不在 Roblox Studio 的对象浏览器中。

你无法使用 Instance.new 构造器创建此类别的实例。

Roblox 不会在跨服务器与客户机界限而复制此成员。

Lua 编程码无法访问此成员。你可能可以从 Roblox Studio 的属性窗口更改其值。

此会员可以从 OpenCloud Luau 执行任务访问。

此对象的复制行为取决于拥有它的玩家。

此成员可以通过命令行和插件访问。从脚本尝试访问此成员将导致错误。

此成员为只读。尝试写入此成员将会导致错误。

此属性为只读，可以从未同步的线程读取。尝试写入可能会导致错误。

可使用其他终端节点来取代此终端节点。

只有 Roblox CoreScript 可以访问此成员，Players 不可用。

你可以安全地从多线程对此属性进行读写。

此类别为顶级类单例。使用 GetService 函数获取此类别的实例。

可在通过 {link1Start}RunService:BindToSimulation(){link1End} 绑定的回调中访问。参与回滚。请参阅{link2Start}服务器权限{link2End}。

多线程可以写入此属性，所以从未同步的线程读取将会有风险。

此函数在返回借过前将会暂停调用自己的的线程。此操作不会中断其他脚本。