环境函数

什么是环境函数？

环境函数是旨在根据运行时环境（代码在客户端还是服务器上运行）定义和控制函数执行的实用工具。这些实用工具帮助确保环境特定的逻辑安全且有意地执行，从而防止运行时错误并提高全栈或同构应用程序的可维护性。

Start 提供三个核心环境函数：

createIsomorphicFn：组合一个适用于客户端和服务器环境的单一函数。
serverOnly：确保函数只能在服务器上运行。
clientOnly：确保函数只能在客户端运行。

同构函数

使用 createIsomorphicFn() 来定义根据在客户端还是服务器上调用而行为不同的函数。这对于安全地跨环境共享逻辑，同时将环境特定行为委托给适当的处理程序非常有用。

完整实现

tsx

import { createIsomorphicFn } from '@tanstack/react-start'

const getEnv = createIsomorphicFn()
  .server(() => 'server')
  .client(() => 'client')

const env = getEnv()
// ℹ️ On the **server**, it returns `'server'`.
// ℹ️ On the **client**, it returns `'client'`.

import { createIsomorphicFn } from '@tanstack/react-start'

const getEnv = createIsomorphicFn()
  .server(() => 'server')
  .client(() => 'client')

const env = getEnv()
// ℹ️ On the **server**, it returns `'server'`.
// ℹ️ On the **client**, it returns `'client'`.

部分实现（服务器）

这是一个只有服务器实现的 createIsomorphicFn() 示例

tsx

import { createIsomorphicFn } from '@tanstack/react-start'

const serverImplementationOnly = createIsomorphicFn().server(() => 'server')

const server = serverImplementationOnly()
// ℹ️ On the **server**, it returns `'server'`.
// ℹ️ On the **client**, it is no-op (returns `undefined`)

import { createIsomorphicFn } from '@tanstack/react-start'

const serverImplementationOnly = createIsomorphicFn().server(() => 'server')

const server = serverImplementationOnly()
// ℹ️ On the **server**, it returns `'server'`.
// ℹ️ On the **client**, it is no-op (returns `undefined`)

部分实现（客户端）

这是一个只有客户端实现的 createIsomorphicFn() 示例

tsx

import { createIsomorphicFn } from '@tanstack/react-start'

const clientImplementationOnly = createIsomorphicFn().client(() => 'client')

const client = clientImplementationOnly()
// ℹ️ On the **server**, it is no-op (returns `undefined`)
// ℹ️ On the **client**, it returns `'client'`.

import { createIsomorphicFn } from '@tanstack/react-start'

const clientImplementationOnly = createIsomorphicFn().client(() => 'client')

const client = clientImplementationOnly()
// ℹ️ On the **server**, it is no-op (returns `undefined`)
// ℹ️ On the **client**, it returns `'client'`.

无实现

这是一个没有环境特定实现的 createIsomorphicFn() 示例

tsx

import { createIsomorphicFn } from '@tanstack/react-start'

const noImplementation = createIsomorphicFn()

const noop = noImplementation()
// ℹ️ On both **client** and **server**, it is no-op (returns `undefined`)

import { createIsomorphicFn } from '@tanstack/react-start'

const noImplementation = createIsomorphicFn()

const noop = noImplementation()
// ℹ️ On both **client** and **server**, it is no-op (returns `undefined`)

什么是空操作（no-op）？

空操作（no-op，"no operation" 的缩写）是一个执行时什么都不做的函数——它只是返回 undefined，不执行任何操作。

tsx

// basic no-op implementation
function noop() {}

// basic no-op implementation
function noop() {}

envOnly 函数

serverOnly 和 clientOnly 辅助函数强制执行严格的环境绑定执行。它们确保被修饰的函数只能在正确的运行时上下文中调用。如果误用，它们会抛出描述性运行时错误，以防止意外的逻辑执行。

serverOnly

tsx

import { serverOnly } from '@tanstack/react-start'

const foo = serverOnly(() => 'bar')

foo() // ✅ On server: returns "bar"
// ❌ On client: throws "serverOnly() functions can only be called on the server!"

import { serverOnly } from '@tanstack/react-start'

const foo = serverOnly(() => 'bar')

foo() // ✅ On server: returns "bar"
// ❌ On client: throws "serverOnly() functions can only be called on the server!"

clientOnly

tsx

import { clientOnly } from '@tanstack/react-start'

const foo = clientOnly(() => 'bar')

foo() // ✅ On client: returns "bar"
// ❌ On server: throws "clientOnly() functions can only be called on the client!"

import { clientOnly } from '@tanstack/react-start'

const foo = clientOnly(() => 'bar')

foo() // ✅ On client: returns "bar"
// ❌ On server: throws "clientOnly() functions can only be called on the client!"

注意

这些函数对于 API 访问、文件系统读取、使用浏览器 API 或其他在其预期环境之外无效或不安全的操作非常有用。