教程 · 玩家数据

Roblox Studio 怎么用 DataStore 保存玩家数据

除非服务端脚本保存了,否则 Roblox 在两次游戏之间不会记住玩家的任何东西。在本教程中,你会搭建一个 PlayerData 模块,通过 DataStoreService 加载、在内存中保存并写回每个玩家的数据,然后再了解测试方法、各项限制,以及已保存的数据是怎么丢失的。

更新于 2026年11月20日阅读约 3 分钟作者

要点

在 服务端 Script 中使用 DataStoreService:玩家进入时用 GetAsync 加载他的数据,游戏期间把数据放在一张表里,并用 UpdateAsync 定时保存、在玩家离开时(PlayerRemoving)保存、在服务器关闭时(game:BindToClose)保存。把每次调用都包在 pcall 里,失败时重试几次。

  • 要在 Studio 中测试,先发布场景,然后在一个单独的测试游戏中开启 File > Experience Settings > Security > Enable Studio Access to API Services:Studio 使用的数据和正式服务器是同一份。
  • 如果玩家的数据没有加载成功,永远不要保存这个玩家。保存默认值会覆盖他真实的进度。
  • 每个玩家用一个键存一张表,例如 User_12345,并定时保存,而不是每次改动都保存。
  • 对于交易物品或付费物品,加上会话锁,让两台服务器不能同时保存同一个玩家。
本页内容
  1. Studio 访问
  2. DataStore 原理
  3. GetAsync 和 UpdateAsync
  4. 1. PlayerData 模块
  5. 模块的结构
  6. 2. 使用数据
  7. 3. 提醒
  8. 4. 在 Studio 中测试
  9. 数据为什么会丢失
  10. 会话锁
  11. 限制
  12. 版本和备份
  13. Common errors
  14. With RoCode
  15. 常见问题
  16. 参考资料

开始之前:在测试副本中开启 Studio 访问

在你允许之前,Studio 中运行的游戏无法访问数据存储。这个权限有一个 Roblox 文档特别提醒的陷阱:开启后 Studio 读写的是 和正式游戏相同的数据存储,所以一个在 Studio 中把你的金币清零的测试,也会把正式游戏里的金币清零,测试代码中的错误还可能损坏真实玩家的键。

  1. 做一个测试副本。把场景保存为文件,打开副本,选择 File > Publish to Roblox As 并点击 Create new game。不要把它作为一个场景加进正式游戏里:同一个游戏的所有场景共享同一套数据存储。
  2. 在测试副本中打开 File > Experience Settings,进入 Security。
  3. 开启 Enable Studio Access to API Services 并点击 Save。

数据存储调用只能在服务端 Script 中使用;尝试调用的 LocalScript 会报错,所以客户端无法写入保存的数据。当某个按钮需要修改它们时,客户端通过 RemoteEvent 请求服务器,由服务器决定(见 RemoteEvent 教程,英文)。

数据存储是怎么保存玩家数据的

示意图教程第 4 步的测试加速版:Play,Stop 把会话保存到数据存储,再次 Play 时加载它,所以 Output 显示 200。

数据存储(data store)是 Roblox 服务器上一组有名字的键和值,由你的游戏的所有服务器和所有场景共享。DataStoreService:GetDataStore("PlayerData") 返回一个这样的存储。

Roblox 的建议可以归结为一条规则:玩家数据用一个存储,每个玩家一个键,每个键一张表。用玩家的 UserId 组成键,例如 User_12345,永远不要用他可以修改的名字。固定的 User_{UserId} 格式还能让 Roblox 针对被遗忘权的自动处理找到玩家的数据,前提是你配置了它。

数据存储中可以保存什么
类型能保存吗?说明
数字、字符串、布尔值、缓冲区能字符串必须是有效的 UTF-8。不要保存 inf 或 nan。
表能前提是里面的所有东西也都能保存。数字键不从 1 开始的表(因此长度为 0)取回时,这些键会变成字符串。
Instance、Vector3、CFrame、Color3不能保存时会报错或写入 nil。请保存物品的名字,或者把位置存成三个数字。

每个请求都是一次可能失败的网络调用,需要时间,还会消耗每分钟的预算。所以可靠的保存系统会在玩家进入时读取一次数据,游戏期间把数据放在服务端的表里,并时不时地写回去。

GetAsync、SetAsync 还是 UpdateAsync:选哪个

数据存储的主要方法
方法作用用途
GetAsync(key)读取值。结果会在这台服务器上缓存 4 秒。加载玩家数据
SetAsync(key, value)不读取就覆盖值。一次写入。新键,或者不依赖旧值的值
UpdateAsync(key, callback)读取最新的值,把它传给你的函数,并写入函数返回的结果。一次读取和一次写入。保存玩家数据,以及任何可能被多台服务器写入的键
IncrementAsync(key, delta)给保存的整数加上一个整数。计数器
RemoveAsync(key)删除键并返回旧值。以前的版本仍然可以列出和读取。删除玩家数据

SetAsync 是盲写:如果两台服务器几乎同时保存同一个键,最后写入的那个获胜,不管里面是什么。UpdateAsync 会先读取当前值,如果在这期间有另一台服务器写入,Roblox 会用新值再次运行你的函数。只要写入依赖当前值,或者键可能被多台服务器写入,Roblox 都建议使用它,而玩家数据正是这种情况。这个函数有三条规则:

  • 它不能让出执行(yield):里面不能有 task.wait() 和其他数据存储调用。
  • 它可能执行不止一次,所以只能计算新值,永远不要发放物品或触发事件。
  • 返回 nil 会取消写入。模块利用这一点,避免覆盖由更新版本的游戏保存的数据。

第 1 步:创建 PlayerData 模块

这个 ModuleScript 是唯一和数据存储打交道的代码。它在玩家进入时加载数据,把数据放在内存中,每 180 秒、玩家离开时和服务器关闭时保存,并拒绝保存数据没有加载成功的玩家。

  1. 在 Explorer 中把鼠标悬停在 ServerScriptService 上,点击 + 并插入一个 ModuleScript。把它重命名为 PlayerData,用下面的代码替换它的内容。
  2. ModuleScript 只有在某个脚本引用(require)它时才会运行。在 ServerScriptService 中插入一个名为 Main 的 Script,写上这一行:local PlayerData = require(game:GetService("ServerScriptService").PlayerData)。其他服务端脚本也用同样的方式引用它。
  3. 按你的游戏修改 DEFAULTS 和 Data 类型,每个字段都保持为数字、字符串、布尔值或表。
完成第 1 到 3 步后的 Explorer
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript 位置: ServerScriptService 名称: PlayerData
-- PlayerData:玩家进入时加载数据,把数据放在内存中,
-- 并定时、在玩家离开时和服务器关闭时保存。
-- 其他服务端脚本通过 PlayerData.Get(player) 读取和修改数据。

local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")

local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- 数据结构变化时调高它,并在 migrate() 中加一步
local AUTOSAVE_SECONDS = 180
-- 在 Studio 中失败的调用会立即放弃,这样没有存储访问权限的测试也能很快跑完
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- 每次失败后翻倍:1、2、4

export type Data = {
	SchemaVersion: number,
	Coins: number,
	Level: number,
	Inventory: { string },
}

-- 全新玩家的初始数据
local DEFAULTS: { [string]: any } = {
	Coins = 0,
	Level = 1,
	Inventory = {},
}

type Session = {
	key: string,
	userId: number,
	data: Data,
	canSave: boolean, -- 加载失败时为 false:默认数据不能替换真实的进度
}

-- 在下面的每个 pcall 内部调用,所以还没发布的场景
-- (没有存储访问权限)也能用默认数据加载玩家
local function store(): DataStore
	return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- 按键记录仍在进行中的保存
local loadedEvent = Instance.new("BindableEvent")

local PlayerData = {}

-- 玩家的数据准备好时带上这个玩家触发。表请通过 PlayerData.Get(player) 获取:
-- 通过 BindableEvent 发送的表到达时是一份副本,修改它不会有任何效果。
PlayerData.Loaded = loadedEvent.Event

local function deepCopy(value: any): any
	if type(value) ~= "table" then
		return value
	end
	local copy = {}
	for key, item in value do
		copy[key] = deepCopy(item)
	end
	return copy
end

local function defaultData(): Data
	local data = deepCopy(DEFAULTS) -- 全新的副本,这样玩家之间永远不会共用一张 Inventory 表
	data.SchemaVersion = SCHEMA_VERSION
	return data
end

-- 把保存的数据转换成当前的结构。如果无法安全使用,返回 nil。
local function migrate(saved: any): Data?
	if type(saved) ~= "table" then
		return nil
	end
	local version = tonumber(saved.SchemaVersion) or 1
	if version > SCHEMA_VERSION then
		return nil -- 由更新版本的游戏保存:在这里既不加载也不覆盖
	end

	-- 每次结构变化一步,从旧到新
	if version < 2 then
		-- 示例:版本 1 中货币叫 Gold。只有在没有 Coins 时才复制它,
		-- 这样已经有 Coins 但没有 SchemaVersion 的旧数据会保留原值。
		if saved.Coins == nil then
			saved.Coins = saved.Gold
		end
		saved.Gold = nil
	end

	-- 补上玩家上次保存之后新增的字段,并替换类型不对的值
	for field, default in DEFAULTS do
		if type(saved[field]) ~= type(default) then
			saved[field] = deepCopy(default)
		end
	end
	saved.SchemaVersion = SCHEMA_VERSION
	return saved
end

-- 在 pcall 中执行数据存储调用。失败时等待并重试,每次把等待时间翻倍
-- 并加上一点随机性,这样服务器不会全部同时重试。
local function withRetries(label: string, call: () -> any): (boolean, any)
	for attempt = 1, MAX_ATTEMPTS do
		local ok, result = pcall(call)
		if ok then
			return true, result
		end
		warn(`{label} failed (attempt {attempt} of {MAX_ATTEMPTS}): {result}`)
		if attempt < MAX_ATTEMPTS then
			local waitTime = FIRST_RETRY_SECONDS * 2 ^ (attempt - 1)
			task.wait(waitTime + math.random() * waitTime / 2)
		end
	end
	return false, nil
end

local function save(session: Session): boolean
	if not session.canSave then
		return false
	end
	local key = session.key
	pendingSaves[key] = (pendingSaves[key] or 0) + 1

	local newerSchema = false
	local ok = withRetries(`Save {key}`, function()
		return store():UpdateAsync(key, function(current: any)
			if type(current) == "table" and (tonumber(current.SchemaVersion) or 1) > SCHEMA_VERSION then
				newerSchema = true
				return nil -- 返回 nil 会取消写入
			end
			-- 写入当前的整张表,并标记玩家的 UserId
			return session.data, { session.userId }
		end)
	end)

	local left = (pendingSaves[key] or 1) - 1
	if left > 0 then
		pendingSaves[key] = left
	else
		pendingSaves[key] = nil
	end
	if newerSchema then
		session.canSave = false
		warn(`{key} was saved by a newer version of the game, so this server stopped saving it`)
	end
	return ok and not newerSchema
end

local function startAutosave(player: Player, session: Session)
	task.spawn(function()
		-- 从间隔中的随机时刻开始,这样服务器不会全部同时保存
		task.wait(math.random() * AUTOSAVE_SECONDS)
		while sessions[player] == session do
			save(session)
			task.wait(AUTOSAVE_SECONDS)
		end
	end)
end

local function load(player: Player)
	local key = "User_" .. player.UserId

	-- 如果玩家刚从这台服务器离开又回来了,先等上一次保存完成
	while pendingSaves[key] do
		task.wait()
	end

	local ok, saved = withRetries(`Load {key}`, function()
		return store():GetAsync(key)
	end)
	if player.Parent ~= Players then
		return -- 加载期间离开了:什么都没变,没有要保存的
	end

	local data: Data? = nil
	if ok then
		data = if saved == nil then defaultData() else migrate(saved)
	end

	local session: Session = {
		key = key,
		userId = player.UserId,
		data = data or defaultData(),
		canSave = data ~= nil,
	}
	if not session.canSave then
		warn(`Could not load {key}. {player.Name} is playing on default data that will not be saved.`)
	end

	sessions[player] = session
	player:SetAttribute("DataLoaded", session.canSave) -- GUI 可以读取它来提醒玩家
	startAutosave(player, session)
	loadedEvent:Fire(player)
end

local function endSession(player: Player)
	local session = sessions[player]
	if not session then
		return
	end
	sessions[player] = nil -- 停止自动保存循环,再次调用也不会做任何事
	save(session)
end

-- 玩家的实时数据表,加载完成前为 nil。只能在服务端脚本中修改它。
function PlayerData.Get(player: Player): Data?
	local session = sessions[player]
	return if session then session.data else nil
end

-- 当玩家的数据已加载并且会被保存时为 true。任何出售之前都要检查。
function PlayerData.CanSave(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and session.canSave
end

-- 立即保存而不等计时器,用于购买等重要时刻。
-- 会让出执行,保存成功时返回 true。
function PlayerData.SaveNow(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and save(session)
end

Players.PlayerAdded:Connect(load)
Players.PlayerRemoving:Connect(endSession)
for _, player in Players:GetPlayers() do
	task.spawn(load, player) -- 在这个模块第一次被引用之前就进入的玩家
end

game:BindToClose(function()
	-- 服务器给这些函数 30 秒,所以同时保存所有人
	for player in sessions do
		task.spawn(endSession, player)
	end
	-- 然后等待所有仍在进行的保存,包括在 PlayerRemoving 中开始的
	while next(pendingSaves) do
		task.wait()
	end
end)

return PlayerData

游戏上线后,不要修改 STORE_NAME 和键格式 User_。修改其中任何一个都会让模块指向空的键,每个玩家都会从默认值重新开始。

模块如何保护数据

默认值和结构版本

新玩家会得到一份全新的 DEFAULTS 副本。必须是副本:如果所有玩家共用一张 Inventory 表,加给一个玩家的物品就会出现在所有人那里。

每张保存的表都带有 SchemaVersion。添加字段不需要新版本,因为 migrate 会用默认值补上缺少的字段。重命名或重组则需要:调高 SCHEMA_VERSION 并加一步,就像示例中把 Gold 重命名为 Coins 那样(在新游戏中删掉它,从 1 开始)。版本高于服务器的数据来自正在推出的更新版本,所以旧服务器不会碰它。

加载失败的数据永远不会被保存

这条规则防止数据被彻底抹掉。如果所有加载尝试都失败了,玩家会用默认数据来玩,但 canSave 为 false,所以这些值永远不会覆盖他真实的进度。模块还会把 DataLoaded 属性设为 false,第 3 步用它来通知玩家。Roblox 的参考示例也这样处理加载失败,并建议用它代替踢出;如果你更想踢出玩家,就在模块输出警告的地方调用带消息的 player:Kick()。

等待时间递增的重试

withRetries 把每次调用都包在 pcall 里。失败后它依次等待 1、2、4 秒,每次再加上最多一半时长的随机时间,并在四次尝试后停止(在 Studio 中一次后停止,这样没有存储访问权限的场景能立即启动)。随机性让大量服务器在故障后的重试错开,而上限把等待控制在大约 10 秒内,在服务器关闭时得到的 30 秒以内。由于每次保存都通过 UpdateAsync 写入整张实时表,迟到完成的重试不会把旧数据写回来。

模块什么时候保存

什么时候为什么
玩家在服务器上时每 180 秒一次限制崩溃时的损失。第一次保存落在间隔中的随机时刻,这样服务器不会全部同时保存。Roblox 的参考示例也使用 180 秒。
玩家离开时(PlayerRemoving)常规的最后一次保存。会话先被删除,所以自动保存会停止。
服务器关闭时(game:BindToClose)还在服务器上的所有人一起保存,函数会等待每个进行中的保存。Roblox 给它 30 秒。
按需,通过 PlayerData.SaveNow(player)在发生不能丢失的事情之后,例如购买。

如果玩家在最后一次保存还在进行时重新进入同一台服务器,新的加载会等这次保存结束,所以不会读到旧值。

第 2 步:在其他脚本中读取和修改数据

所有引用这个模块的服务端脚本都操作同一批表:

调用作用
PlayerData.Get(player)玩家的实时数据表,加载完成前为 nil。直接修改字段,例如 data.Coins += 10,下一次保存就会包含它。
PlayerData.Loaded玩家的数据准备好时带上这个玩家触发,加载失败后也会触发。只传递玩家,因为通过 BindableEvent 发送的表到达时是一份副本。
PlayerData.CanSave(player)加载失败时为 false。任何出售之前都要检查:无法保存的购买会在玩家离开时消失。
PlayerData.SaveNow(player)立即保存,成功时返回 true。会让出执行。

模块是保存的数据唯一存在的地方,leaderstats 只是用来显示:按 排行榜教程 搭建它,在 Loaded 处理函数中用 PlayerData.Get(player) 填充,值变化时两边都更新。永远不要从 leaderstats 读回保存的值,也永远不要让第二个脚本保存同一个键。

在玩家进入之后才引用模块的脚本,会错过这些玩家的 Loaded。先连接处理函数,然后再遍历 Players:GetPlayers(),处理所有 PlayerData.Get(player) 已经返回表的玩家。

要替换旧的保存脚本,例如排行榜教程中的那个?它的值留在它自己的存储和键中,所以这个模块会让所有人从默认值开始。上线前,要么把 STORE_NAME 和前缀 User_ 指向旧的(migrate 会把没有 SchemaVersion 的数据当作版本 1 并补上缺少的字段),要么迁移旧值,然后删掉旧脚本。

客户端永远不会直接修改这些数据。商店按钮触发一个 RemoteEvent;服务器检查 CanSave,把价格和玩家的 Coins 比较,修改表并调用 SaveNow。商店 GUI 教程 在服务端搭建了这样的购买。

添加字段的现成示例见 点击模拟器教程:它把 PowerLevel 和 Rebirths 加进 DEFAULTS 和 Data 类型,然后在 PlayerData.Get 返回的表中修改它们。migrate 会把新字段补给有旧存档的玩家。

第 3 步:告诉玩家他的数据没有加载成功

数据没有加载成功的玩家应该知道这次游戏不会被保存,好重新进入,而不是白玩一场。这个 LocalScript 监听 DataLoaded 属性,当它为 false 时显示一个横幅。

LocalScript 位置: StarterPlayerScripts 名称: DataWarning
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local shown = false

local function showWarning()
	if shown or player:GetAttribute("DataLoaded") ~= false then
		return
	end
	shown = true

	local gui = Instance.new("ScreenGui")
	gui.Name = "DataWarning"
	gui.ResetOnSpawn = false

	local label = Instance.new("TextLabel")
	label.AnchorPoint = Vector2.new(0.5, 0)
	label.Position = UDim2.new(0.5, 0, 0, 12)
	label.Size = UDim2.new(0.8, 0, 0, 48)
	label.BackgroundColor3 = Color3.fromRGB(110, 28, 28)
	label.TextColor3 = Color3.new(1, 1, 1)
	label.TextScaled = true
	label.Text = "Your saved progress could not be loaded. Nothing you do in this server will be saved, so rejoin later."
	label.Parent = gui

	gui.Parent = player:WaitForChild("PlayerGui")
end

-- 服务器在尝试加载这个玩家的数据之后设置一次 DataLoaded
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()

第 4 步:在 Studio 中测试保存

请在开启了 Studio 访问的测试副本中进行。

  1. 给自己一些可以保存的东西。在 Main 中 require 那一行的下面加上:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. 点击 Play。Output 窗口(在 Window 菜单或 Script 选项卡中)会显示你的名字和 100(第一次运行时),没有 Could not load 警告。
  3. 点击 Stop。结束测试会关闭服务器,模块会在关闭前保存你的数据。
  4. 再次点击 Play。Output 应该显示 200,比上次多 100。如果它又显示同样的数字,说明保存没有成功:看看它上面的警告。
  5. 测试出错的情况。关闭 Studio 访问并点击 Play。经过几秒的重试后,Output 会显示 Could not load User_... 和 100,并出现第 3 步的横幅。停止测试,重新开启访问并点击 Play:Output 会显示 300,即你保存的 200 加上 100,因为失败的会话从来没有覆盖你的数据。
  6. 从 Main 中删掉测试代码。

玩家数据为什么会丢失

下面是保存系统丢失进度的常见方式。模块在代码中解决了前四条和关于结构的那一条;其余的取决于你保存什么以及怎么保存,最后一条则需要会话锁。

发生了什么结果如何预防
加载失败,但脚本照样保存默认值覆盖真实进度:数据被彻底抹掉永远不要保存加载失败的玩家
只在 PlayerRemoving 中保存服务器崩溃或关闭时漏掉保存自动保存,再加上等待自己的保存完成的 BindToClose
没有 pcall 或没有重试一次失败的请求就会让脚本停止或丢失一次保存pcall 加上几次时间错开的重试
每次改动都保存请求排起队;队列满 30 个时新的请求会被丢弃把数据放在内存中并定时保存
保存存储无法保存的东西保存时报错,或者取回的值为 nil保存数字、字符串、布尔值以及由它们组成的表
改变数据结构却不做迁移旧存档被加载进错误的字段结构版本和迁移步骤
两个脚本保存同一个键每次保存都覆盖另一个脚本的字段一个键只归一个模块管理
两台服务器持有同一个玩家持有旧数据的服务器最后保存,覆盖了新的进度会话锁

会话锁、“lock lost”和 ProfileStore

玩家同一时间只连接一台服务器,但当他进入新服务器时,旧服务器的最后一次保存可能还在进行:缓慢的重试、传送或快速重进。如果新服务器先加载数据,它拿到的就是旧数据,而最后保存的那台服务器会获胜。Roblox 文档指出,在有交易的游戏中,这个时间窗口是物品复制的常见原因。

会话锁 关闭了这个窗口。服务器加载玩家的键时,会在同一次 UpdateAsync 调用中把自己的锁 ID 写进键的元数据。任何其他服务器发现一个未过期、且不是自己设置的锁时,都不会加载或保存这个键。持有者在每次自动保存时刷新锁,并在最后一次保存时释放它;如果它不再刷新,锁就会过期,其他服务器可以接手。

“lock lost”是什么意思

在使用会话锁的系统中,当玩家的键现在归另一台服务器所有时(因为锁过期或被抢走),这台服务器就失去了锁。它的副本可能已经过时,所以它必须停止保存这个玩家;常见的处理方式是:带消息把他踢出,让他重新连接。如果你作为玩家看到了“lock lost”,那是那个游戏自己的保存系统发出的消息,只有它的开发者能解释。

你需要它吗?

本教程的模块不使用会话锁。没有锁时,真实的最坏情况是:在罕见的竞争中,玩家会丢失他在旧服务器上最后一次成功保存之后获得的东西。当复制或丢失会让玩家损失真正有价值的东西时再加上锁:交易、developer products、稀有物品或频繁传送。

方案是什么需要知道的
本教程的模块加载、内存缓存、重试、自动保存、关闭时保存和结构版本,没有锁足够短,可以完整读懂并修改
Roblox 的玩家数据和购买示例Roblox 提供的参考代码,带会话锁、按键顺序重试和购买收据处理Roblox 表示它没有在热门游戏中经受过时间考验,在没有大量测试的情况下不应直接使用
ProfileStore免费的开源社区模块,ProfileService 的继任者,围绕会话锁和自动保存构建不是 Roblox 出品。把现有游戏迁移到它需要迁移已经保存的数据

对于任何第三方模块,Roblox 建议检查它归谁所有、是否还在维护,以及没有它时你如何访问自己的数据。同一份文档把 DataStore2 称为过时的库,新游戏不应该使用。

数据存储的限制

这些是 Roblox 文档中截至 2026 年 9 月 30 日的限制。Roblox 会调整它们,所以在依赖某个确切数字之前,请查看 错误代码和限制页面(英文)。

每台服务器每分钟的默认请求限制
请求类型普通存储有序存储
读取:GetAsync、UpdateAsync 中的读取60 + 40 × 玩家数60 + 40 × 玩家数
写入:SetAsync、IncrementAsync、UpdateAsync 中的写入60 + 40 × 玩家数30 + 5 × 玩家数
列表:ListKeysAsync,有序存储为 GetSortedAsync5 + 2 × 玩家数5 + 2 × 玩家数
删除:RemoveAsync60 + 40 × 玩家数30 + 5 × 玩家数

有 20 个玩家时,服务器每分钟可以进行 860 次普通写入;这个模块的自动保存大约用掉其中 7 次,再加上每个离开的玩家一次。每捡一枚金币就保存一次才会耗尽预算。第二个预算作用于整个游戏,并与 Open Cloud 共享:每分钟 300 次读取加上每个在线玩家 40 次,以及 300 次写入加上每个玩家 20 次。

大小和吞吐量限制
限制数值
存储名、键名、scope各 50 个字符
一个键中的值JSON 形式 4,194,304 个字符
所有服务器读取一个键每分钟 25 MB
所有服务器写入一个键每分钟 4 MB,每个请求向上取整到下一个 KB
等待中的请求每个队列 30 个;超出后请求会以 301-306 错误失败
整个游戏的存储空间500 MB,加上历史上每个用户 1 MB

用 #HttpService:JSONEncode(data) 测量玩家数据的大小,用 DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite) 查看正式服务器剩余的预算。由 4 秒缓存响应的 GetAsync 调用不计入。Studio 的 Run 模式有自己的、可能更低的限制,所以 Roblox 建议用 Team Create 测试请求限制。

版本和备份

普通数据存储会替你保存历史。每个 UTC 小时内对键的第一次写入会被保存为一个版本,这一小时内之后的写入会互相覆盖。旧版本在被更新的写入替换 30 天后过期;最新的版本永远不会过期。有序存储不保存版本。

要回滚某个玩家,打开 Data Stores Manager(Creations,你的游戏,Configure > Data Stores Manager),选择他的键,选择一个更早的版本并点击 Revert;这需要 Edit 权限。请在玩家不在线时操作,否则持有他会话的服务器会把自己的副本保存到回滚之上。在服务端脚本中,ListVersionsAsync 和 GetVersionAsync 可以找到并读取旧版本,然后你再把它作为当前值写回去。

在发布会改变数据保存方式的更新之前,Roblox 建议通过 Open Cloud Snapshot Data Stores API 做一次快照(每个游戏每天一次)。没有快照的话,3:30 UTC 的一次错误保存会覆盖从 3:00 起写入这个键的所有内容,因为它落在同一个小时版本中。

常见错误与解决办法

数据存储错误会出现在 Studio 的 Output 窗口中,模块在每次尝试失败时都会输出带有 Roblox 错误文本的警告。脚本错误教程 解释了 Output 的一般读法。

StudioAccessToApisNotAllowed(错误 403)

“Can't write to DataStore from Studio because API access is not enabled.” 先发布场景,然后在测试副本中开启 File > Experience Settings > Security 里的 Enable Studio Access to API Services。

DataStore request was added to queue

服务器发送请求的速度超出了预算,或者过于频繁地写入同一个键,通常是因为每次改动都保存或在循环里保存。队列中有 30 个请求时,新的请求会以 301-306 错误失败。把数据放在内存中并定时保存。

CantStoreValue(错误 104),或者某个字段取回时是 nil

表里有存储无法保存的东西,例如 Instance、Vector3 或 Color3。改为保存名字、ID 或简单的数字,并在加载时还原对象。

ValueTooLarge(错误 105)

一个键保存了超过 4,194,304 个 JSON 字符。用 #HttpService:JSONEncode(data) 测量,去掉可以重建的内容,或者把数据拆分到几个固定的键中。

没有报错,但数据没有保存

找找模块的 Could not load 警告:加载失败后它会故意拒绝保存。否则,值很可能是在 LocalScript 中修改的,而那永远不会到达服务器,或者另一个脚本在保存同一个键。

每次重新进入数据都被重置

键在两次会话之间变了(用 player.Name 组成,或者你改了 STORE_NAME),加载失败而你看到的是默认值,或者没有任何脚本引用这个模块,所以它根本没有运行。检查 Output,并确认 Main 引用了 PlayerData。

用 RoCode 构建

如果不想手动搭建这些,RoCode 可以直接在你打开的场景里完成。它是独立的 AI 代理,并非 Roblox 出品,通过 Roblox Studio 插件工作:它编写像任何脚本一样使用 DataStoreService 的 Luau,并在你的 Explorer 中创建脚本。它自己从不访问你的数据存储,但使用插件 3.9 及以上时,它可以点击 Play 进行简短的试玩测试,你的脚本会像在任何测试中一样运行。

你输入

给我的游戏加上保存功能:在 PlayerData 模块中保存 Coins、Level 和 Inventory,带自动保存和服务器关闭时保存,并在我已有的 leaderstats 中显示 Coins。

RoCode 的操作
  • 可以用 Search Scripts 和 Read Script 查找已有的 leaderstats 和 DataStore 代码,以便扩展你已有的东西,而不是再加第二个保存脚本。在大型场景中,请在消息里写明脚本或文件夹的名字。
  • 用 Create Script 创建 ModuleScript 和引用它的 Script,或者用 Edit Script 修改已有的脚本
  • 对写好的每个脚本运行 Check Script:这是在 Studio 内部进行的编译检查,附带一份简短的警告列表,而不是类型检查,也不是测试运行
  • 分批发送改动,每一批都是 Studio 中的一个撤销点(undo)

在测试副本中开启 Studio Access to API Services 仍然需要你自己来做:RoCode 无法修改这个设置。使用插件 3.9 及以上时,它的简短试玩测试会读取错误;使用插件 3.9.11 及以上时,它可以操控一个测试角色来检查游戏是否正常运行,但它只检查自己决定要检查的内容,所以请亲自玩一下,确认 Coins、Level 和 Inventory 能被保存和加载。如果在你的测试中保存失败了,Check Output 可以读取你运行的试玩测试中的 Server 输出行。保存功能通常在核心玩法循环已经能运行之后再加;用 AI 一次一个系统地做 Roblox 游戏 展示了这个顺序。RoCode 如何连接到 Studio。

常见问题

Roblox Studio 里怎么开启 DataStore?

发布场景,打开 File > Experience Settings > Security,开启 Enable Studio Access to API Services 并点击 Save。请在一个单独的测试游戏中操作,因为开启后 Studio 使用的是和这个游戏的正式服务器相同的数据存储。

Roblox 会自动保存玩家数据吗?

不会。除非服务端脚本通过 DataStoreService 保存,否则玩家的任何东西在会话结束后都不会保留,leaderstats 也一样。

选 ProfileStore 还是直接用 DataStoreService?

ProfileStore 同样建立在数据存储之上,所以问题在于你是否希望别人替你编写和维护会话锁。对于交易、付费物品或频繁传送,锁是值得的,可以来自这个库或 Roblox 的参考示例。对于小一些的游戏,像这样的模块更容易阅读和修改。

怎么重置或删除玩家的数据?

在 Data Stores Manager 中找到键并选择 Mark for Deletion,这在等待期内可以撤销;或者在服务端脚本中对这个键调用 RemoveAsync。请在玩家不在线时操作,否则他所在服务器的下一次保存会把数据写回去。在测试副本中,修改 STORE_NAME 会让所有人从零开始;永远不要在正式游戏中这样做。

参考资料

代码如何验证:本页的所有脚本都已用 Roblox API 类型定义(luau-lsp,2026年11月20日)通过 Luau strict 类型检查。类型检查能发现 API 名称写错和类型不匹配,但发现不了游戏逻辑上的错误。发布前请务必在 Studio 中测试。

在你自己的游戏里试试 RoCode。

每天有免费额度,无需绑定银行卡。安装插件,描述你想要的功能,然后看看它在 Studio 里做了什么。