Back to Details

taubyte-build-runtime-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Build runtime config

构建运行时配置

When to use

适用场景

Use whenever a resource needs server-side build logic, runtime environment variables, or deployment-time setup. For Go functions, also load 
taubyte-go-sdk-constraints
.
当资源需要服务端构建逻辑、运行时环境变量或部署时设置时使用。对于Go函数，还需加载**
taubyte-go-sdk-constraints
**。

How builds are triggered

构建触发方式

  1. Resource code and config are pushed to GitHub (normal 
    git push
    workflow for the function, website, or library repo as appropriate).
  2. Remote cloud
    After the push, the cloud is reached from GitHub (webhook). Builds trigger automatically — no extra inject step on your machine.
  3. Local Dream
    GitHub cannot call into your laptop, so webhooks do not drive Dream the same way. After pushing to GitHub you must trigger the build from the local machine using Dream inject:
    CommandUse for
    dream inject push-all
    		Config and code for the whole project — run from the project root (
    --path
    = absolute project root).
    dream inject push-specific
    		Individual resource repos that need their own inject after a full sync — e.g. libraries and websites (per-resource repo path and identifiers).
    Always run 
    push-all
     successfully before 
    push-specific
     when both apply. Universe, Docker, and flag details (e.g. 
    --rid
    , 
    --fn
    for websites) live in 
    taubyte-dream-local-operations
    .
  1. 资源代码与配置推送至GitHub（针对函数、网站或库仓库的常规
    git push
    工作流）。
  2. 远程云端
    推送完成后，GitHub通过webhook连接云端。构建会自动触发——无需在本地执行额外的注入步骤。
  3. 本地Dream
    GitHub无法访问你的笔记本电脑，因此webhook无法以同样方式驱动Dream。推送至GitHub后，你必须在本地机器上通过Dream inject触发构建：
    命令用途
    dream inject push-all
    		整个项目的配置与代码——需在项目根目录运行（
    --path
    = 项目根目录绝对路径）。
    dream inject push-specific
    		需要单独注入的单个资源仓库——例如库和网站（需指定资源仓库路径及标识符）。
    当两种命令都适用时，务必先成功运行**
    push-all
    ，再运行
    push-specific
    。Universe、Docker及参数细节（如网站的
    --rid
    、
    --fn
    ）可参考
    taubyte-dream-local-operations
    **。

Targets

目标路径

  • Function: 
    <project>/code/.../functions/<name>/.taubyte/
  • Website repo: 
    <project>/websites/tb_website_<name>/.taubyte/
  • Library repo: 
    <project>/libraries/tb_library_<name>/.taubyte/
  • 函数：
    <project>/code/.../functions/<name>/.taubyte/
  • 网站仓库：
    <project>/websites/tb_website_<name>/.taubyte/
  • 库仓库：
    <project>/libraries/tb_library_<name>/.taubyte/

Required checks

必要检查

  1. .taubyte/config.yaml
     exists and is valid (image, workflow, etc. — not runtime env var declarations).
  2. .taubyte/build.sh
     exists, is non-empty, writes output Taubyte expects (e.g. function wasm + ret-code, website assets under 
    /out
    ).
  3. Runtime env vars (if any) are set in 
    .taubyte/build.sh
     (e.g. 
    export …
    before build steps), not in 
    config.yaml
    .
  1. .taubyte/config.yaml
     存在且有效（包含镜像、工作流等——不包含运行时环境变量声明）。
  2. .taubyte/build.sh
     存在且非空，能输出Taubyte所需内容（例如函数wasm文件+返回码，网站资源存于
    /out
    目录下）。
  3. 运行时环境变量（如有）需在**
    .taubyte/build.sh
    **中设置（例如构建步骤前使用
    export …
    ），不要放在
    config.yaml
    中。

Function 
config.yaml
pattern

函数
config.yaml
模板

yaml
version: 1.00
environment:
  image: taubyte/go-wasi:latest
workflow:
  - build
Keep 
config.yaml
 for image/workflow and similar metadata only.
yaml
version: 1.00
environment:
  image: taubyte/go-wasi:latest
workflow:
  - build
**
config.yaml
**仅用于存储镜像/工作流等元数据。

Function 
build.sh
pattern

函数
build.sh
模板

bash
#!/bin/bash
. /utils/wasm.sh
bash
#!/bin/bash
. /utils/wasm.sh

Runtime env for this build (example — use real names/values your code expects):

本次构建的运行时环境（示例——使用代码实际需要的名称/值）：

export MY_VAR=value

export MY_VAR=value

build "${FILENAME}" ret=$? echo -n $ret > /out/ret-code exit $ret

---
build "${FILENAME}" ret=$? echo -n $ret > /out/ret-code exit $ret

---

Website 
build.sh
(technology-specific)

网站
build.sh
（技术栈专属）

Website 
build.sh
is not one generic script — it must match how that repo is built (package manager, 
package.json
scripts, and especially where the bundler writes static files). Treating every Node site like Vite (always 
dist/
) is wrong for Create React App and other stacks that emit 
build/
 or another directory.
Always
  • Produce a non-empty 
    /out
     (Taubyte’s deploy staging path inside the build environment — not the same as a framework’s own 
    out
    folder name on disk).
  • Put build-time env here with 
    export
    , not in 
    config.yaml
    .
Pick the pattern from the repo
Read 
package.json
 (
scripts.build
or equivalent) and the framework docs to learn the real output directory, then copy that tree into 
/out
.
Examples (illustrative — adjust to the project)
  • Plain static (no bundler):
    bash
    #!/bin/bash
cp index.html /out/
  • Vite (default output 
    dist/
    ):
    bash
    #!/bin/bash
npm ci
npm run build
cp -r dist/* /out/
  • Create React App / 
    react-scripts
     (output 
    build/
    , not 
    dist/
    ):
    bash
    #!/bin/bash
npm ci
npm run build
cp -r build/* /out/
  • Other stacks (Next, Nuxt, custom webpack, etc.): run that project’s install + production build commands, then 
    cp -r <framework-output-dir>/* /out/
     using the directory that tool actually generates (check docs and a local build once if unsure).
网站的**
build.sh
并非通用脚本**——它必须匹配该仓库的构建方式（包管理器、
package.json
脚本，尤其是打包工具输出静态文件的路径）。将所有Node站点都当作Vite（默认输出
dist/
）处理是错误的，因为Create React App等技术栈的输出目录是**
build/
**或其他目录。
务必
  • 生成非空的**
    /out
    **目录（这是构建环境中Taubyte的部署临时路径——与框架自身磁盘上的
    out
    文件夹名称不同）。
  • 在此处通过**
    export
    设置构建时环境变量**，而非在
    config.yaml
    中。
根据仓库选择模板
查看**
package.json
**（
scripts.build
或等效字段）及框架文档，了解实际输出目录，然后将该目录下的所有内容复制到
/out
中。
示例（仅供参考——需根据项目调整）
  • 纯静态站点（无打包工具）：
    bash
    #!/bin/bash
cp index.html /out/
  • Vite（默认输出**
    dist/
    **）：
    bash
    #!/bin/bash
npm ci
npm run build
cp -r dist/* /out/
  • Create React App / 
    react-scripts
    （输出**
    build/
    **，而非
    dist/
    ）：
    bash
    #!/bin/bash
npm ci
npm run build
cp -r build/* /out/
  • 其他技术栈（Next、Nuxt、自定义webpack等）：运行该项目的安装+生产构建命令，然后使用工具实际生成的目录执行**
    cp -r <framework-output-dir>/* /out/
    **（若不确定，可查看文档并在本地构建一次确认）。

Rules

规则

  • Env vars: declare and use them in 
    .taubyte/build.sh
     only; do not put runtime env declarations in 
    .taubyte/config.yaml
     for this purpose.
  • Websites: tailor 
    build.sh
     to the actual framework and build output (e.g. Vite → 
    dist/
    , CRA → 
    build/
    ); never copy a Vite-only script onto a React-CRA repo without changing paths and commands.
  • Do not push to GitHub before validating 
    .taubyte/build.sh
     and 
    .taubyte/config.yaml
    .
  • After changing build/config, remote cloud: rely on webhook-driven builds after push; Dream: run 
    dream inject push-all
     and, for website/library resource repos, 
    dream inject push-specific
     as required, then verify logs/build per 
    taubyte-push-build-verify
    .
  • Document notable env or build assumptions in the context log (
    taubyte-context-log
    ).
  • For Go compile issues, validate handler code against 
    taubyte-go-sdk-constraints
    .
  • 环境变量：仅在**
    .taubyte/build.sh
    中声明和使用；切勿为该目的在
    .taubyte/config.yaml
    **中声明运行时环境变量。
  • 网站：根据实际框架和构建输出调整**
    build.sh
    （例如Vite → 
    dist/
    **，CRA → 
    build/
    ）；切勿直接将仅适用于Vite的脚本复制到React-CRA仓库而不修改路径和命令。
  • 在验证**
    .taubyte/build.sh
    和
    .taubyte/config.yaml
    **之前，不要推送至GitHub。
  • 修改构建/配置后，远程云端：推送后依赖webhook驱动构建；Dream：运行**
    dream inject push-all
    ，对于网站/库资源仓库，按需运行
    dream inject push-specific
    ，然后根据
    taubyte-push-build-verify
    **验证日志/构建结果。
  • 在上下文日志（
    taubyte-context-log
    ）中记录值得注意的环境或构建假设。
  • 若遇到Go编译问题，需根据**
    taubyte-go-sdk-constraints
    **验证处理器代码。