企业官网建设流程全解析

Build Output API 通配符（Wildcard）域名路由实战：基于域名的多语言静态站点分发

【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples

导读

本指南聚焦 Vercel Build Output API 的wildcard（通配符）路由能力，通过 build-output-api/wildcard 预构建（Prebuilt）示例，讲解如何让多个域名（或子域名）指向同一个 Deployment，并根据请求的域名把流量路由到不同的静态页面。读完本文，你将掌握wildcard配置的完整写法、$wildcard占位符的引用方式，并能独立实现"一个部署、多语言子域名"的典型场景。

示例概览：Domain-Based Routing（基于域名的路由）

这是本仓库 build-output-api 目录下 11 个 Build Output API 预构建示例之一。该示例的在线演示地址为https://build-output-api-wildcard.vercel.sh，访问主域名会得到一个包含四个语言子域名入口的索引页：

• en.build-output-api-wildcard.vercel.sh→ 英文（English）
• es.build-output-api-wildcard.vercel.sh→ 西班牙语（Español）
• fr.build-output-api-wildcard.vercel.sh→ 法语（Français）
• pt.build-output-api-wildcard.vercel.sh→ 葡萄牙语（Português）

四个子域名全部指向同一个Deployment，却各自渲染出对应语言的页面。索引页实现位于 .vercel/output/static/index.html，四个语言页面分别是english.html、spanish.html、french.html、portuguese.html，均存放在 .vercel/output/static/ 目录下。

核心原理：wildcard 配置如何工作

在 Build Output API 中，.vercel/output/config.json是预构建项目的路由配置文件。其中的wildcard配置允许你声明任意数量的域名（或子域名），这些域名指向同一个 Deployment，但会根据实际请求的域名路由到特定的页面。最常见的用途就是本文示例所展示的：基于域名提供本地化（多语言）内容版本。

其工作流程如下：

1. 请求到达平台后，系统将请求的域名与wildcard数组中的domain字段逐一匹配；
2. 命中匹配时，该条目的value会被注入到路由配置中；
3. 路由配置通过$wildcard占位符引用这个值，实现动态路由。

$wildcard占位符有两种典型用法：

• 按文件名路由到静态文件：如本例所示，把 wildcard 值拼进dest路径，指向对应的静态 HTML；
• 作为查询字符串参数追加：把 wildcard 值作为 query-string 参数传给 Edge Function 或 Serverless Function，在函数内根据该值做业务分发。

完整配置逐行解析

本示例的完整配置如下（文件：.vercel/output/config.json）：

{ "version": 3, "wildcard": [ { "domain": "en.build-output-api-wildcard.vercel.sh", "value": "english" }, { "domain": "es.build-output-api-wildcard.vercel.sh", "value": "spanish" }, { "domain": "fr.build-output-api-wildcard.vercel.sh", "value": "french" }, { "domain": "pt.build-output-api-wildcard.vercel.sh", "value": "portuguese" } ], "routes": [{ "src": "/", "dest": "/$wildcard.html" }] }

version: 3

声明项目遵循 Build Output API v3 规范，这是使用wildcard配置的前提。整个 build-output-api 目录下的示例均为符合 Build Output API 规范的"预构建（Prebuilt）"项目。

wildcard数组

数组中的每个对象由两个字段组成：

value并不要求与文件名一致，它只是一个"映射键"——例如你可以把value设为us、de、jp之类的代码，再在routes中把它映射到任意目标。

routes与$wildcard占位符

"routes": [{ "src": "/", "dest": "/$wildcard.html" }]

• src: "/"：匹配站点根路径的请求；
• dest: "/$wildcard.html"：把请求重写（rewrite）到$wildcard占位符展开后的路径。

当用户请求fr.build-output-api-wildcard.vercel.sh时，匹配到domain: "fr.build-output-api-wildcard.vercel.sh"、value: "french"，于是请求被重写到/french.html，最终由 .vercel/output/static/french.html 响应。

静态文件目录：预构建输出的存放约定

与 Next.js 等框架项目由构建工具自动产出不同，Build Output API 项目要求开发者自行把产物放进约定目录。本示例的输出目录结构为：

build-output-api/wildcard/ └── .vercel/output/ ├── config.json # 路由与 wildcard 配置 └── static/ # 静态资源目录 ├── index.html ├── english.html ├── spanish.html ├── french.html └── portuguese.html

.vercel/output/static/是 Build Output API 存放静态文件的约定目录，config.json中的routes路由目标即相对于该目录解析。各语言页面均为极简的纯文本 HTML，例如 english.html 内容为This page was served in english，spanish.html 为Esta página fue servida en español，french.html 为Cette page a été servie en français，portuguese.html 为Esta página foi veiculada em português。它们体积小巧、职责单一，非常适合作为演示 wildcard 路由命中效果的载体。

部署方式

这类预构建项目无需任何框架构建流程，直接使用 Vercel CLI 即可部署。根据 build-output-api 总览文档 的说明，在示例目录内执行：

vercel deploy --prebuilt

--prebuilt标志告诉 CLI 跳过构建阶段，直接使用仓库中已有的.vercel/output目录内容进行部署。部署前请确保：

• 已安装并登录 Vercel CLI；
• 将config.json中声明的子域名（如en.build-output-api-wildcard.vercel.sh）正确绑定到该 Deployment；
• 域名解析已生效，使请求能够到达对应部署。

部署完成后，即可通过不同子域名访问同一部署下的不同语言页面，验证基于域名的路由效果。

扩展思路：从静态页面到动态分发

虽然本示例只演示了静态文件路由，但$wildcard占位符的能力不止于此。将 wildcard 值作为查询参数传递给函数即可扩展出更复杂的业务逻辑，例如：

{ "version": 3, "wildcard": [ { "domain": "en.example.com", "value": "en" }, { "domain": "de.example.com", "value": "de" } ], "routes": [ { "src": "/api/hello", "dest": "/api/hello?lang=$wildcard" } ] }

这样，Edge Function 或 Serverless Function 便能在运行时读取lang参数，依据语言代码动态返回本地化内容或调用对应语种的第三方服务。从源码结构看，本仓库的 build-output-api 目录还收录了 routes、serverless-functions、edge-functions 等示例，可与本示例组合阅读，理解路由规则与函数分发的完整能力边界。

小结

通过wildcard配置与$wildcard占位符，Vercel Build Output API 让"单部署、多域名、按域名分发"成为一行配置即可完成的工作：wildcard负责域名 → 值的映射，routes负责值 → 目标的转发。本示例以四个语言子域名为载体，完整演示了该机制从配置文件到静态文件命中的全过程，是构建多语言站点、地域化落地页等场景的可靠参考范式。

【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples