Cesium 搭建指南 中英文对照表

Build Guide 搭建指南

• Build Guide 搭建指南
  • Quickstart 快速入门
  • Get the Code 获取代码
  • Build the Code 构建代码
    • Development Server 开发服务器
    • Build Output 构建输出
  • Build Scripts 构建脚本
  • Continuous Integration 持续集成
    • Configure a Different S3 Bucket
      配置不同的 S3 存储桶
    • Configure S3 Credentials 配置S3凭证

Quickstart 快速入门

1. Clone the repository 克隆存储库

2. Install the dependencies 安装依赖项

    npm install
   

3. Start the server
   启动服务器

   npm start
   

4. Navigate to : http://localhost:8080/
   导航到： http://localhost:8080/

---

Get the Code 获取代码

• Setup Git if it isn’t already (

  link

  ).

  如果尚未设置 Git（链接）。

  • New to git or need a refresher? Now’s a good time to learn! Easy tutorials here.
    刚接触 git 或者需要复习一下？现在正是学习的好时机！这里有简单的教程。

  • Make sure your SSH keys are configured (linux | mac | windows).
    确保您的 SSH 密钥已配置 ( linux | mac | windows )。

  • Double-check your settings for name and email: git config --get-regexp user.*.
    仔细检查您的姓名和电子邮件设置： git config --get-regexp user.* 。

  • Recommended Git settings:

    推荐的 Git 设置：

    • git config --global fetch.prune true - when fetching remote changes, remove any remote branches that no longer exist on the remote.
      git config --global fetch.prune true - 获取远程更改时，删除远程上不再存在的任何远程分支。

• Have

  commit access

  to CesiumJS?

  拥有 CesiumJS 的提交权限吗？

  • No

    不

    • Fork cesium.
      叉铯。
    • Use the GitHub website to delete all branches in your fork except main.
      使用GitHub 网站删除分支中除main之外的所有分支。
    • Clone your fork, e.g., git clone git@github.com:yourusername/cesium.git.
      克隆您的分支，例如git clone git@github.com:yourusername/cesium.git 。
    • Make changes in a branch, e.g., git checkout -b my-feature.
      在分支中进行更改，例如git checkout -b my-feature 。

  • Yes

    是的

    • Clone the cesium repo, e.g., git clone git@github.com:CesiumGS/cesium.git
      克隆 cesium 存储库，例如git clone git@github.com:CesiumGS/cesium.git
    • Make changes in a branch, e.g., git checkout -b my-feature.
      在分支中进行更改，例如git checkout -b my-feature 。

Build the Code 构建代码

Prerequisites: 先决条件：

• Install Node.js on your system. Building Cesium requires Node 18.x or newer.
  在您的系统上安装Node.js。构建 Cesium 需要 Node 18.x 或更高版本。

Cesium uses npm modules for development, so after syncing, you need to run npm install from the Cesium root directory:
Cesium使用npm模块进行开发，因此同步后，您需要从Cesium根目录运行npm install ：

npm install

Cesium ships with a simple HTTP server for testing. Once all modules have been installed, run npm start to use it:
Cesium 附带了一个简单的 HTTP 服务器用于测试。安装所有模块后，运行npm start来使用它：

npm start

Then browse to http://localhost:8080/. The landing page includes apps and tools commonly used during development, including:
然后浏览到http://localhost:8080/ 。登陆页面包括开发过程中常用的应用程序和工具，包括：

• Hello World : an example for how to create a 3D globe. Tutorial here
  Hello World ：如何创建 3D 地球仪的示例。教程在这里
• Sandcastle : an app for viewing and creating [code examples](https://sandcastle.cesium.com/?src=Hello World.html&label=Showcases), complete with a live preview
  Sandcastle ：一个用于查看和创建[代码示例的](https://sandcastle.cesium.com/?src=Hello World.html&label=Showcases)应用程序，并带有实时预览。
• Test Suites : tests using Jasmine. Testing guide here.
  测试套件：使用Jasmine进行测试。测试指南在这里。
• Documentation : reference documentation built from source. Documentation guide here.
  文档：从源代码构建的参考文档。文档指南在这里。

Development Server 开发服务器

By default, the server only allows connections from your local machine. To allow connections from other machines, pass the --public option to npm. Note the extra -- is intentional and required by npm.
默认情况下，服务器仅允许来自本地计算机的连接。要允许来自其他计算机的连接，请将--public选项传递给 npm。请注意，额外的--是 npm 有意为之且要求的。

npm start -- --public

The development server has a few other options as well, which you can see by passing the --help parameter:
开发服务器还有一些其他选项，您可以通过传递--help参数来查看：

npm start -- --help

Build Output 构建输出

Cesium offers a few different distributions. When developing, make sure to pick the one that fits your app’s architecture.
Cesium 提供了几种不同的发行版。开发时，请确保选择适合您的应用程序架构的一种。

• IIFE (immediately-invoked function expression) - A pre-processed bundle, optimized for the browser, and with web worker code inlined. It defines a Cesium global variable upon loading Build/Cesium/Cesium.js. This is what is available via the CDN. While much of our documentation uses IIFE-style globals for ease-of-use, we do not recommend this approach for production apps.
  IIFE（立即调用函数表达式） - 一个预处理包，针对浏览器进行了优化，并内联了 Web Worker 代码。它在加载Build/Cesium/Cesium.js时定义了一个Cesium全局变量。这是通过 CDN 提供的内容。虽然我们的大部分文档都使用 IIFE 样式的全局变量以方便使用，但我们不建议在生产应用程序中使用这种方法。
• ESM (ECMAScript modules) - Standard for packaging JS code which is supported by most browsers and NodeJS. Modules use import and export statements. Unprocessed, individual modules are available in the Source directory, accessible by importing Source/Cesium.js; A single pre-processed bundle by importing Build/Cesium/index.js.
  ESM（ECMAScript 模块） - 大多数浏览器和 NodeJS 都支持的打包 JS 代码的标准。模块使用import和export语句。未处理的单个模块位于Source目录中，可通过导入Source/Cesium.js进行访问；通过导入Build/Cesium/index.js进行单个预处理的包。
• CJS (CommonJS) - A pre-processed, bundled module packaged for running in NodeJS accessible by requiring index.cjs.
  CJS (CommonJS) - 一个经过预处理的捆绑模块，打包后可在 NodeJS 中运行，通过需要index.cjs即可访问。

In much of our documentation, we use IIFE as it can be easily loaded with a CDN and defines a global Cesium variable with all modules attached.
在我们的大部分文档中，我们使用 IIFE，因为它可以轻松地通过 CDN 加载，并定义一个附加所有模块的全局Cesium变量。

For a production app, we recommend using the Source modules directly which will allow your build tool of choice to reduce the final release’s size using tree shaking.
对于生产应用程序，我们建议直接使用Source模块，这将允许您选择的构建工具使用树摇动来减少最终版本的大小。

Read the complete list of build scripts and options below for more details.
请阅读下面的构建脚本和选项的完整列表以了解更多详细信息。

While you can use the editor of your choice to develop Cesium, certain files, such as glsl and new tests, require that the build task be executed in order for the changes to take effect. You can use the build-watch script to have this happen automatically.
虽然您可以使用您选择的编辑器来开发 Cesium，但某些文件（例如glsl和新测试）需要执行build任务才能使更改生效。您可以使用build-watch脚本自动执行此操作。

Build Scripts 构建脚本

Cesium uses gulp for build tasks, but they are all abstracted away by npm run scripts.
Cesium 使用gulp来构建任务，但它们都被npm run script抽象掉了。

Specify the target(s) at the command line:
在命令行指定目标：

npm run [target-name]

Here’s the full set of scripts and what they do.
这是完整的脚本集及其作用。

• Build scripts

  – build and package the source code and documentation

  构建脚本——构建并打包源代码和文档

  • build
    

    - A fast, developer-oriented build that bundles the source modules to produce all-in-one files in the

    Build/CesiumUnminified
    

    directory that exposes the entire Cesium API attached to a single global

    Cesium
    

    object. Run this when a GLSL shader is changed since the .glsl file is converted to a .js file with a string for the GLSL source.

    build - 一种快速、面向开发人员的构建，它捆绑源模块以在Build/CesiumUnminified目录中生成一体化文件，该目录公开附加到单个全局Cesium对象的整个 Cesium API。当 GLSL 着色器发生更改时运行此命令，因为 .glsl 文件已转换为带有 GLSL 源字符串的 .js 文件。

    • --minify - Minifies the output for optimized loading. Specifying this option will output to Build/Cesium.
      --minify -缩小输出以优化加载。指定此选项将输出到Build/Cesium 。
    • --removePragmas - Optimizes the output by removing debugging code that validates function input and throws DeveloperErrors. The removed sections are marked with //>>includeStart('debug', pragmas.debug); blocks in the code.
      --removePragmas - 通过删除验证函数输入并抛出DeveloperError的调试代码来优化输出。删除的部分标有//>>includeStart('debug', pragmas.debug);代码中的块。
    • --node - Bundles an index.cjs module targeted for use in NodeJS
      --node - 捆绑一个旨在在 NodeJS 中使用的index.cjs模块

  • build-watch - A never-ending task that watches your file system for changes to Cesium and builds the source code as needed. All build options are also available for this task.
    build-watch - 一个永无止境的任务，用于监视文件系统对 Cesium 的更改并根据需要构建源代码。所有build选项也可用于此任务。

  • build-apps - Builds the example applications (such as Cesium Viewer) to produce self-contained, minified, deployable versions in the Build directory.
    build-apps - 构建示例应用程序（例如 Cesium Viewer）以在Build目录中生成独立的、精简的、可部署的版本。

  • build-docs - Generates HTML documentation in Build/Documentation using JSDoc 3. See the Documentation Guide for more details.
    build-docs - 使用JSDoc 3在Build/Documentation中生成 HTML 文档。有关更多详细信息，请参阅文档指南。

  • build-ts - Generates a TypeScript definitions file for the Cesium library
    build-ts - 为 Cesium 库生成 TypeScript 定义文件

  • build-third-party - Generates ThirdParty.json, a file which lists the latest licensing information of installed third party modules
    build-third-party - 生成ThirdParty.json ，该文件列出了已安装的第三方模块的最新许可信息

  • release - A full release build that creates a shippable product, including generating documentation.
    release - 创建可交付产品的完整发布版本，包括生成文档。

  • make-zip - Builds a zip file containing all release files. This includes the source ESM modules, bundled ESM and IIFE format Cesium.js, plus the bundled minified versions of ESM and IIFE, the generated documentation, the test suite, and the example applications (in both built and source form).
    make-zip - 构建包含所有发布文件的 zip 文件。这包括源 ESM 模块、捆绑的 ESM 和 IIFE 格式Cesium.js ，以及捆绑的 ESM 和 IIFE 缩小版本、生成的文档、测试套件和示例应用程序（内置形式和源形式）。

• Utility scripts

  – code coverage, static code analysis, and other utilities

  实用程序脚本——代码覆盖率、静态代码分析和其他实用程序

  • clean - Removes all generated build artifacts
    clean - 删除所有生成的构建工件
  • cloc - Runs CLOC to count the lines of code on the Source and Specs directories. This requires Perl to execute.
    cloc - 运行CLOC来计算 Source 和 Specs 目录中的代码行数。这需要Perl来执行。
  • coverage - Runs coverage and opens the default browser with the results
    coverage - 运行覆盖范围并打开默认浏览器并显示结果
  • eslint - Runs ESLint, a static code analysis tool, on the entire source tree
    eslint - 在整个源代码树上运行静态代码分析工具ESLint
  • prettier - Formats the code base using Prettier
    prettier - 使用Prettier格式化代码库
  • prettier-check - Verifies prettier formatting, but does not write the output
    prettier-check - 验证更漂亮的格式，但不写入输出

• Testing scripts

  – build and run the unit tests

  测试脚本——构建并运行单元测试

  • test - Runs all tests with Karma using the default browser specified in the Karma config file.
    test - 使用 Karma 配置文件中指定的默认浏览器运行Karma的所有测试。
  • test-all - Runs all tests with Karma using all browsers installed on the current system
    test-all - 使用当前系统上安装的所有浏览器运行 Karma 的所有测试
  • test-non-webgl - Runs only non-WebGL tests
    test-non-webgl - 仅运行非 WebGL 测试
  • test-webgl - Runs only WebGL tests
    test-webgl - 仅运行 WebGL 测试
  • test-webgl-stub - Runs all tests using the WebGL stub, which WebGL calls a noop and ignores related test expectations
    test-webgl-stub - 使用 WebGL 存根运行所有测试，WebGL 将其称为 noop 并忽略相关的测试期望
  • test-webgl-validation - Runs all tests with Karma and enables low-level WebGL validation
    test-webgl-validation - 使用 Karma 运行所有测试并启用低级 WebGL 验证
  • test-release - Runs all tests on the minified release version of built Cesium
    test-release - 在构建的 Cesium 的缩小版本上运行所有测试

• Deployment scripts 部署脚本

  • deploy-status - Sets the deployment statuses in GitHub, for use in CI
    deploy-status - 设置 GitHub 中的部署状态，以在 CI 中使用
  • deploy-set-version - Sets the version of package.json, for use in CI
    deploy-set-version - 设置package.json的版本，以在 CI 中使用

Continuous Integration 持续集成

Cesium uses GitHub Actions for continuous integration. Reusable actions are defined in /.github/actions/ and workflows in .github/workflows/.
Cesium 使用GitHub Actions进行持续集成。可重用的操作在/.github/actions/中定义，工作流在.github/workflows/中定义。

(Although outdated, the blog post Cesium Continuous Integration contains background on the CesiumJS CI process.)
（尽管已经过时，博客文章Cesium Continuous Integration包含了 CesiumJS CI 流程的背景知识。）

A workflow is triggered whenever someone pushes code to the Cesium repository, or an external contributor opens a pull request. After the build has completed, at the bottom of the pull request page the status of the build is shown. In the dropdown menu, individual checks are displayed. Logs and deployed artifacts can be accessed by clicking the “Details” link.
每当有人将代码推送到 Cesium 存储库或外部贡献者打开拉取请求时，就会触发工作流程。构建完成后，拉取请求页面的底部会显示构建的状态。在下拉菜单中，显示各个检查。可以通过单击“详细信息”链接来访问日志和已部署的工件。

The build of any branch of CesiumJS can be accessed under the Branches page, and clicking the icon next to the branch name.
CesiumJS 任何分支的构建都可以在“分支”页面下访问，然后单击分支名称旁边的图标。

Additional set up is required for deployment if you do not have commit access to Cesium.
如果您没有对 Cesium 的提交访问权限，则需要进行额外的部署设置。

Configure a Different S3 Bucket 配置不同的 S3 存储桶

It is possible to configure your development branch of CesiumJS to deploy build artifacts to a different AWS S3 Bucket. If you are using the cesium-public-builds bucket and have valid credentials, skip to Configure S3 Credentials
可以配置 CesiumJS 的开发分支以将构建工件部署到不同的AWS S3 Bucket 。如果您使用 cesium-public-builds 存储桶并具有有效凭证，请跳至配置 S3 凭证

• In .gtihub/workflows/dev.yml, in the following lines, replace “cesium-public-builds” with the name of your S3 bucket.
  在.gtihub/workflows/dev.yml中的以下行中，将“cesium-public-builds”替换为您的 S3 存储桶的名称。

aws s3 sync ./Build/Coverage s3://cesium-public-builds/cesium/$BRANCH/Build/Coverage --delete --color on

aws s3 sync Build/unzipped/ s3://cesium-public-builds/cesium/$BRANCH/Build/ --cache-control "no-cache" --delete

• In gulpfile.js, edit the following line:
  在gulpfile.js中，编辑以下行：

const devDeployUrl = "https://ci-builds.cesium.com/cesium/";

• Edit the URL to match the URL hosting the S3 bucket specified in the previous step.
  编辑 URL 以匹配托管上一步中指定的 S3 存储桶的 URL。

Configure S3 Credentials 配置S3凭证

To configure CI for deployment for a fork of Cesium, you must have valid credentials to an S3 bucket.
要为 Cesium 分支配置 CI 部署，您必须拥有 S3 存储桶的有效凭据。

• Go to your fork of Cesium
  转到你的Cesium分支
• Click the Setting tab
  单击设置选项卡
• In the left sidebar, under the Security section, click Secrets and Variables > Actions
  在左侧边栏中的**“安全”部分下，单击“机密和变量”** > “操作”
• Under Repository secrets add two environment variables, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, with your access key and secret key
  在Repository Secrets下添加两个环境变量AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY以及您的访问密钥和秘密密钥

** tab
单击设置选项卡

• In the left sidebar, under the Security section, click Secrets and Variables > Actions
  在左侧边栏中的**“安全”部分下，单击“机密和变量”** > “操作”
• Under Repository secrets add two environment variables, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, with your access key and secret key
  在Repository Secrets下添加两个环境变量AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY以及您的访问密钥和秘密密钥