开发环境设置与构建、服务等命令

以下说明将指导你如何为本网站设置开发环境。

云端 IDE 设置

Gitpod

通过 Gitpod.io 使用开发环境：

1. Fork 本仓库。参考 Fork a repository 获取帮助。

2. 在 gitpod.io/workspaces 中创建一个新的工作空间（仅需一次）或在你的 fork 上打开一个已有的工作空间。你也可以访问以下格式的链接： https://gitpod.io#https://.com/YOUR__ID/opentelemetry.io

   注意：如果你有权限直接在此仓库工作，或只是想浏览一下，请打开： https://gitpod.io/#https://.com/open-telemetry/opentelemetry.io

Gitpod 会自动为你安装与仓库相关的依赖包。 你现在已经可以开始构建、提供并更新网站文件。

Codespaces

通过 Codespaces 使用开发环境：

1. Fork 此网站仓库。
2. 从你的 fork 中打开一个 Codespace。

开发环境将通过 DevContainer 配置初始化。 你现在已经可以开始构建、提供并更新网站文件。

本地开发设置

1. Fork 并 克隆 网站仓库，地址为：https://.com/open-telemetry/opentelemetry.io

2. 进入仓库目录：

   cd opentelemetry.io
   

3. 安装或升级到 Node.js 的当前 LTS 版本。我们推荐使用 nvm 来管理 Node 安装。在 Linux 下运行以下命令，它会根据 .nvmrc 中指定的版本进行安装和升级：

   nvm install
   

   若需在 Windows 上安装 Node.js，使用 nvm-windows：

   nvm install lts && nvm use lts
   

4. 安装 npm 包和其他依赖项：

   npm install
   

启动你喜欢的 IDE。 你现在已经可以开始构建、提供并更新网站文件。

构建网站

要构建网站，请运行：

npm run build

生成的站点文件将位于 public 目录中。

启动本地服务

要启动本地服务，请运行：

npm run serve

网站将通过 localhost:1313 提供服务。

如果你需要测试 Netlify 重定向，请使用以下命令，并访问 localhost:8888：

npm run serve:netlify

serve 命令是从内存中提供文件，而不是从磁盘读取。

如果你在 macOS 上看到类似 too many open files 或 pipe failed 的错误， 你可能需要提高文件描述符限制。请参阅 Hugo issue #6109。

内容与子模块

本网站的构建依赖于以下内容：

• 位于 content/、static/ 等目录下的文件，遵循 Hugo 的默认规则；
• 在 hugo.yaml 中通过 mounts 字段定义的挂载点。这些挂载点来源于 content-modules 目录下的 Git 子模块，或是经过预处理后存放在 tmp/ 目录中的内容，且仅限这两处来源。

子模块更改

如果你更改了某个 content-modules 子模块中的任何内容，你需要先向该子模块的仓库提交一个包含这些更改的 PR。 只有当该 PR 被接受后，你才能更新主仓库中的子模块引用，让这些更改体现在本网站中。

管理 content-modules 更改的最简单方式，是直接在子模块所关联的上游仓库中操作，而不是在子模块目录内部进行编辑。

有经验的贡献者也可以直接在子模块内工作，你可以立即构建并预览你所做的子模块更改。默认情况下， CI 脚本在每次执行时都会拉取最新的子模块。如果你不希望每次都这样，可以设置环境变量 GET=no 以阻止此行为。 同时，在提交 PR 前需要对该子模块运行 git fetch --unshallow。或者，你也可以设置 DEPTH=100 并重新拉取子模块。

DevContainer 支持

本仓库已配置为支持开发容器，这些容器可用于多种云端或本地 IDE，包括（按字母排序）：

• Codespaces
• DevPod
• Gitpod
• VSCode