Terragrunt 官方文档站点开发指南基于 Astro Starlight 的本地构建与 Vercel 部署【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragruntTerragrunt 是一个让基于 OpenTofu/Terraform 编写的基础设施即代码IaC能够规模化编排的灵活工具。本文聚焦于其仓库内docs子项目Terragrunt 官方文档网站托管于 docs.terragrunt.com的本地开发、生产构建与部署全流程。读完本文你将掌握如何使用 mise 与 Bun 一键搭建文档开发环境、启动带热重载的开发服务器、执行带拼写检查与链接校验的生产构建并理解基于 Vercel 的自动部署与预览部署机制以及构建管线中各脚本与配置的源码级细节。Terragrunt 文档仓库概览Terragrunt 官方文档并非与主程序代码混在一起而是作为一个独立的静态站点工程位于仓库的 docs 目录中。它使用 StarlightAstro 生态的文档站点框架构建工程自身包含完整的package.json、astro.config.mjs、vercel.json、Tailwind 与 TypeScript 配置可以独立安装依赖、独立构建、独立部署。从目录结构看文档工程主要由以下几部分组成docs/package.jsonNPM 脚本与依赖清单使用 Bun 作为包管理器与运行时docs/astro.config.mjsAstro/Starlight 核心配置含站点元信息、侧边栏、各类集成插件与大量重定向规则docs/vercel.jsonVercel 平台专属的构建命令、重写、重定向与响应头配置docs/src/content文档正文内容大量.mdx/.md文件docs/src/data命令、标志位、FAQ、Changelog、实验特性等结构化数据集合以.mdx为主docs/scripts/indexnow-ping.js生产构建后向 IndexNow 推送 URL 的脚本docs/tests/install_test.sh对安装脚本的测试套件docs/public/llms.txt面向 LLM/Agent 的手工维护的文档索引。开发环境准备mise 统一工具链文档站点开发的第一步是安装运行所需工具链。仓库使用 mise一个通用的开发工具版本管理器来锁定工具版本保证所有开发者、CI 与本地环境使用一致的版本。安装工具版本在项目根目录执行mise installmise 会根据仓库根目录下的 mise.toml 中声明的[tools]自动下载并安装指定版本的工具。从该文件可以看到 Terragrunt 仓库为整个项目包括 docs 子工程锁定的关键工具版本bun 1.4.0包管理器与脚本运行时docs 工程的所有命令都依赖它go 1.27.0与opentofu 1.12.2Terragrunt 主程序与 OpenTofu 的版本codespell 2.4.1通过 pipx 安装构建阶段的拼写检查器以及golangci-lint、shellcheck、shfmt、pre-commit等静态检查工具。对于只开发文档的场景最关键的其实是bun与codespell两个工具前者驱动所有 NPM 脚本后者在构建前执行拼写检查。安装 NPM 依赖工具链就绪后进入docs目录安装前端依赖cd docs bun i依赖安装使用 Bun 而非 npm/yarn安装记录锁定在 docs/bun.lock 中。核心依赖包括astro7.x、astrojs/starlight0.41.x、astrojs/vercelVercel 适配器、astrojs/sitemap站点地图生成、astro-d2D2 图表渲染、starlight-links-validator链接校验与starlight-llms-txtLLM 友好文本生成等。安装 d2 图表构建工具文档中包含若干用 d2一种声明式图表语言绘制的架构图。这些图在本地构建时需要由d2命令行工具编译为 SVG因此需要额外安装 d2。这一需求同样体现在 docs/astro.config.mjs 中对astro-d2集成的配置上集成在本地构建时执行图表生成skipGeneration为false而在 Vercel 环境存在VERCEL环境变量下则跳过生成——这是因为官方建议在本地生成图表后再提交避免在构建平台上运行非信任代码详见配置中的注释。本地开发启动热重载文档服务器完成依赖安装后即可启动本地开发服务器bun dev该命令实际执行的是astro dev见 docs/package.json 的dev/start脚本。服务器默认监听 http://127.0.0.1:4321并且在你修改任何文档内容时自动热重载HMR无需手动刷新或重启。本地开发模式下还有几个值得注意的行为根路径/会被重定向到/getting-started/quick-start/方便直接进入核心教程历史遗留的/docs/*路径会被重定向到新的/结构例如/docs/→/getting-started/quick-start/这些重定向规则同时定义在 docs/astro.config.mjs 的redirects字段与 docs/vercel.json 中Astro 侧负责astro dev时的行为Vercel 侧负责线上行为大量旧版文档路径如/reference/configuration/、/features/inputs/也配置了到新结构的一一映射保证老链接不失效。生产构建带检查的静态生成当文档内容准备就绪、需要验证能否正常产出时执行生产构建bun run build从 docs/package.json 可以看到build脚本是astro build bun scripts/indexnow-ping.js的组合命令并且配置了prebuild钩子。整个构建流程分三个阶段拼写检查prebuild如果系统 PATH 中存在codespell则先对仓库根目录执行codespell全文拼写检查可通过bun run spell/bun run spell:fix手动触发或自动修复若未安装则跳过并给出提示。这一设计保证了文档在发布前没有明显的拼写错误。Astro 静态构建astro build生成站点产物到dist目录。构建过程会执行额外的检查——例如 docs/astro.config.mjs 中集成的starlight-links-validator会在构建期校验所有站内链接是否有效失效链接会导致构建失败。这也是本地执行构建的一个重要价值当 CI 构建失败时可以本地复现并定位是哪个链接或配置出了问题。IndexNow 推送indexnow-ping.js构建完成后执行 docs/scripts/indexnow-ping.js将站点地图中的所有 URL 分批每批 10000 条提交给 IndexNow 搜索引擎协议加速新内容被搜索引擎收录。IndexNow 脚本的行为细节indexnow-ping.js是一个典型的尽力而为best-effort脚本仅当VERCEL_ENVproduction时才会真正执行其他环境直接打印跳过日志不会报错从.vercel/output/staticVercel 构建产物或dist/client本地 Node 适配器产物中扫描sitemap-*.xml分片提取其中指向 docs.terragrunt.com 的 URL使用仓库中已有的密钥文件7a409eaf64d4ae9f009a70196fd234cd.txt位于 docs/public向 IndexNow API 提交任何网络或响应错误都会被捕获并仅记录日志绝不阻断构建。部署与托管Vercel 自动部署与预览文档站点的托管与部署完全自动化生产环境每当有新提交推送到仓库的main分支Vercel 会自动构建并部署到生产环境docs.terragrunt.com预览环境每一个 Pull Request 都会触发一次预览部署。为防止在 Vercel 构建中运行不可信代码预览站点仅对项目维护者可见见 docs/README.md 的 Hosting 一节。Vercel 侧的行为由 docs/vercel.json 控制其中的关键配置包括构建与安装命令buildCommand为bunx bun1.4.0 run buildinstallCommand为bunx bun1.4.0 install框架识别为astro并开启trailingSlash重写规则rewrites将/api/v1/compatibility按toolopentofu/terraform查询参数分别路由到对应端点将/mtag/*、/vtag/*、/htag/*代理到 Google Tag Manager、Vector 与 HubSpot 等第三方脚本源用于规避 Partytown 工作线程中的跨域 CORS 限制重定向规则redirects将/docs/(.*)永久重定向到/$1与 Astro 侧配合深度路径由 Vercel 处理并处理/lp/*、/contact-tgs/*等营销落地页跳转响应头headers为 Pagefind 搜索资源配置跨域头并为llms.txt、llms-small.txt、llms-full.txt三个文件设置X-Robots-Tag: noindex避免 LLM 索引文件被搜索引擎重复收录。构建管线的源码级细节Astro/Starlight 配置核心docs/astro.config.mjs 是整个文档站的中枢配置值得关注的点包括适配器切换根据是否存在VERCEL环境变量在 Vercel 适配器启用 ISR缓存 24 小时与 Node 独立模式适配器之间切换因此同一份配置既能在本地以 Node 方式运行也能在 Vercel 上以 Serverless 方式运行Starlight 集成站点标题、描述Terragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.、自定义头部组件Header/PageSidebar/SiteTitle/SkipLink、明暗两套 Logo、Kapa AI 文档问答小组件与 Discord 社交链接均在starlight()中声明插件组合starlight-links-validator负责链接校验并对 OpenTelemetry 本地调试地址、动态生成的 CLI 命令页锚点、实验特性页等做了针对性排除starlight-llms-txt生成/llms-full.txt与/llms-small.txtLLM 索引定制配置中通过包装starlight-llms-txt插件拦截其注入的/llms.txt路由将其替换为 docs/public/llms.txt 这份手工维护的索引——因为它比插件自动生成的模板更能准确反映文档结构且按 Getting Started / Features / Guides / Reference / Terragrunt Scale 等板块组织便于 LLM 与 Agent 快速定位内容其他集成astro-d2图表、partytown将 Google Tag Manager 等脚本移入 Web Worker 以提升性能并对不发送 CORS 头的脚本源做了同源代理改写、sitemap刻意省略 changefreq/priority/lastmod因为搜索引擎会忽略或视为噪音。内容集合Collections结构文档内容由 docs/src/content.config.ts 定义的类型化集合驱动共注册了 9 个集合docs核心文档正文使用 Starlight 的docsLoader并扩展了全站 Banner当前提示 Terragrunt v1.0 发布commands/flagsCLI 命令与全局标志位数据存放在 docs/src/data 下命令页由src/pages/reference/cli/commands/[...slug].astro动态组装faq、patterns、changelog、compatibility、experiments、strictControlsFAQ 问答、最佳实践模式、版本变更日志、OpenTofu/Terraform 兼容性矩阵、实验特性与严格控制项。所有集合都带有 Zod schema 校验意味着内容字段缺失或类型错误会在构建期直接报错从数据层面保证了文档的规范性。本地复现 CI 构建失败由于 docs/README.md 明确提到本地运行构建有助于定位 CI 中的构建失败一个推荐的排查流程是mise install # 准备工具链含 codespell cd docs bun i # 安装依赖 bun run build # 本地完整构建拼写检查 astro build IndexNow(no-op)如果本地构建通过而 CI 失败通常可以缩小范围到Vercel 特有的环境差异如VERCEL环境变量导致适配器切换、预览部署的权限限制、bun.lock与本地依赖不一致或indexnow-ping.js在生产环境下的网络行为。整个 docs 工程还配有 docs/tests/install_test.sh 测试套件覆盖安装脚本的语法、参数互斥、校验与平台兼容性等可用./install_test.sh全量运行或--quick跳过联网用例可作为文档工程质量保障的补充参考。小结Terragrunt 的官方文档站是一个独立的 Astro Starlight 工程开发侧通过mise统一工具版本、bun i安装依赖、bun dev热重载预览质量侧通过构建期的 codespell 拼写检查与链接校验把关发布侧则由 Vercel 接管生产与预览部署配合重写/重定向规则、IndexNow 推送与 LLM 友好索引形成一套完整、自动化的文档发布流水线。理解这些配置与脚本无论是为文档贡献内容还是复现构建问题都能做到有的放矢。【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考