在 Vercel 中构建与部署 Stencil Web Components：从组件 Starter 到零配置发布-平芜编程栈

CLI
后端
云原生

【免费下载链接】vercel

Develop. Preview. Ship.

项目地址：https://gitcode.com/gh_mirrors/ve/vercel

本篇技术指南以 Vercel 仓库中 Stencil Component Starter 文档为主体，结合仓库内的 Stencil 组件 fixture 与官方 Stencil 应用示例，完整讲解如何使用 Stencil 编译器构建 100% 标准化的 Web Components、如何组织组件工程结构、如何通过三种策略在任意前端项目中消费这些组件，以及如何将 Stencil 项目部署到 Vercel。读完本文，你将掌握一套从零初始化、本地开发、生产构建、测试到云端发布的可落地实战流程。

Stencil 是什么：把框架能力前移到编译期

Stencil 是一个用于构建 Web Components 的编译器，其核心理念是"编译期（compile-time）而非运行期（run-time）"工具。它在编译阶段吸收主流前端框架的最佳实践——TypeScript、JSX、轻量虚拟 DOM、高效单向数据绑定、类似 React Fiber 的异步渲染管线，以及开箱即用的懒加载——最终生成遵循 Custom Elements v1 规范的、可在任何现代浏览器中运行的标准 Web Components。

这意味着 Stencil 组件本质上就是原生 Web Components：它们可以在任何主流框架（React、Vue、Angular 等）中使用，也可以在完全不使用框架的纯 HTML 页面中使用。正如文档中所强调的，这也是组件命名规范（下文详述）之所以重要的根本原因。

初始化一个 Stencil 组件项目

方式一：克隆 Component Starter（文档推荐）

原文档给出了最直接的起步方式——克隆官方 starter 并清空远端关联：

git clone https://github.com/ionic-team/stencil-component-starter.git my-component cd my-component git remote rm origin

克隆后先安装依赖，即可进入开发循环：

npm install npm start

说明：git remote rm origin用于切断与官方模板仓库的关联，让新项目拥有独立的 Git 历史与远端。

方式二：使用官方初始化器（Vercel 示例采用）

Vercel 仓库的 examples/stencil/readme.md 给出了另一条路径——通过 Stencil 官方项目初始化器创建：

npm init stencil

执行后会以交互方式选择项目类型，生成的项目即可直接对接 Vercel 部署。

三种构建命令：开发、生产与测试

原文档定义了组件开发的核心命令闭环。在 Vercel 仓库的 fixture 中，这些命令被固化为 package.json 的 scripts：

命令	作用	fixture 中的实现
`npm start`	启动开发服务器，监听文件变化并热更新预览	`stencil build --dev --watch --serve`
`npm run build`	执行生产构建，输出可分发产物	`stencil build --docs`（同时生成组件 API 文档）
`npm test`	运行组件单元测试	`stencil test --spec --e2e`（完整应用示例中的测试命令，见 examples/stencil/package.json）

其中--docs参数会触发docs-readme输出目标，为每个组件生成自动更新的 readme 文档。在 fixture 中可以看到由构建自动生成的 my-component 组件文档，它以表格形式记录了组件的全部 Property：

Property	Attribute	Description	Type	Default
`first`	`first`	The first name	`string`	`undefined`
`last`	`last`	The last name	`string`	`undefined`
`middle`	`middle`	The middle name	`string`	`undefined`

深入组件工程：Stencil 项目结构剖析

以 Vercel 仓库中的 Stencil 组件 fixture（packages/static-build/test/fixtures/stencil-v4）为样本，一个标准 Stencil 组件项目包含以下关键部分。

1. 编译器配置：stencil.config.ts

stencil.config.ts 是 Stencil 编译器的配置文件，声明了命名空间与输出目标（outputTargets）：

import { Config } from '@stencil/core'; export const config: Config = { namespace: 'stencil-v4', outputTargets: [ { type: 'dist', esmLoaderPath: '../loader' }, { type: 'dist-custom-elements' }, { type: 'docs-readme' }, { type: 'www', serviceWorker: null }, // disable service workers ], };

各输出目标的含义：

dist：标准库构建输出，供通过 npm 包消费（对应 package.json 中的main、module、es2015、es2017、unpkg等入口字段）；
dist-custom-elements：按自定义元素标准生成的独立模块输出；
docs-readme：为每个组件生成上文所述的自动文档；
www：生成可静态托管的站点产物；此处serviceWorker: null明确关闭了 Service Worker，避免在纯静态部署场景引入不必要的缓存逻辑。

完整应用示例 examples/stencil/stencil.config.ts 还展示了globalStyle（全局样式src/global/app.css）与globalScript（全局脚本src/global/app.ts）的配置方式，并同样通过serviceWorker: null关闭生产环境的 Service Worker。

2. TypeScript 与 JSX 配置：tsconfig.json

tsconfig.json 中值得注意的两个选项：

"jsx": "react"与"jsxFactory": "h"：Stencil 复用 JSX 语法书写组件模板，但编译目标是 Web Components 而非 React 元素；
"experimentalDecorators": true：启用装饰器语法，用于@Component、@Prop等 Stencil 装饰器。

3. 组件实现：tsx 文件

my-component.tsx 展示了 Stencil 组件的最小完整形态：

import { Component, Prop, h } from '@stencil/core'; import { format } from '../../utils/utils'; @Component({ tag: 'my-component', styleUrl: 'my-component.css', shadow: true, }) export class MyComponent { /** The first name */ @Prop() first: string; /** The middle name */ @Prop() middle: string; /** The last name */ @Prop() last: string; private getText(): string { return format(this.first, this.middle, this.last); } render() { return <div>Hello, World! I'm {this.getText()}</div>; } }

几个关键点：

@Component装饰器声明自定义元素标签名（tag）、组件样式与是否启用 Shadow DOM（shadow: true，对应 my-component.css 中以:host选择器控制组件宿主元素）；
@Prop()声明组件的对外属性，即消费方可通过 HTML attribute 传入数据；
render()方法以 JSX 语法返回模板；
组件逻辑可复用外部工具函数，如 utils.ts 中提供的format函数，负责将三个姓名片段拼接为完整字符串。

4. 页面入口：index.html

组件开发预览页 index.html 展示了模块化脚本与降级脚本的加载方式，以及组件的实际用法：

<script type="module" src="/build/stencil-v4.esm.js"></script> <script nomodule src="/build/stencil-v4.js"></script> ... <my-component first="Stencil" last="'Don't call me a framework' JS"></my-component>

现代浏览器加载type="module"的 ESM 版本；
旧浏览器回退到nomodule的降级版本；
组件以自定义标签形式直接书写在 HTML 中，属性即组件@Prop。

组件命名规范：避免使用 stencil 前缀

原文档明确提出一个重要的工程规范：创建新组件标签时，不要在组件名中使用stencil（例如不要写<stencil-datepicker>）。原因很直接——生成的组件与 Stencil 本身几乎无关，它就是一个标准 Web Component！

推荐的实践是使用公司品牌或组件族的统一前缀。例如 Ionic 生态中所有 Web Components 都使用ion前缀。这样既保证了组件命名的语义清晰，又避免了与 Stencil 框架本身产生概念混淆。

消费 Stencil 组件的三种策略

原文档给出了三种向应用引入 Stencil Web Components 的推荐方式，前置条件均为先发布到 NPM 的unpkg字段（dist/stencil-v4/stencil-v4.esm.js）与files字段（dist/、loader/），三种方式分别如下。

策略一：Script 标签直引

将打包产物通过<script>标签引入页面头部，然后即可在模板、JSX 或 HTML 中任意使用组件：

<script type='module' src='https://unpkg.com/my-component@0.0.1/dist/my-component.esm.js'></script>

这是对零构建环境（纯 HTML 页面、CMS 模板等）最友好的方式，npm 包中的 ESM 产物可直接通过 CDN 加载。

策略二：npm 安装 + Script 标签

在项目中先安装依赖，再以本地路径引入模块产物：

npm install my-component --save

<script type='module' src='node_modules/my-component/dist/my-component.esm.js'></script>

这种方式适合不希望依赖远程 CDN 的私有化或离线场景。

策略三：在 Stencil Starter 应用中 import

在 Stencil 组件应用内部，通过 ES Module 导入整包后直接使用：

npm install my-component --save

import my-component;

导入后即可在应用的任意模板位置使用该自定义元素。这种方式依赖dist输出的模块入口（对应 package.json 的module/es2015字段），是组件与应用同属 Stencil 生态时的首选。

将 Stencil 项目部署到 Vercel

Vercel 仓库同时提供了两种 Stencil 部署场景的证据，验证了"零配置部署"的可行性。

场景一：Stencil 应用零配置部署

examples/stencil 是 Vercel 官方提供的 Stencil 应用示例，其文档明确说明：这是一个可以zero configuration（零配置）部署到 Vercel 的 Stencil 应用。它的www输出目标（stencil.config.ts）会生成静态站点产物，Vercel 在构建阶段自动识别 Stencil 项目，执行npm run build并托管www目录下的静态文件。

该示例还演示了组件测试的完整形态：每个组件都配套了.spec.ts（单元测试）与.e2e.ts（端到端测试），例如 app-root.e2e.ts，对应stencil test --spec --e2e命令。

场景二：static-build 构建验证

在 Vercel 的静态构建测试夹具（packages/static-build/test/fixtures/stencil-v4）中，probes.json定义了部署后的验证探针：

{ "probes": [ { "path": "/", "mustContain": "Stencil Component Starter" } ] }

该探针要求访问站点根路径/时，响应内容必须包含 "Stencil Component Starter"（这正是 index.html 的<title>文本）。这从 CI 层面证实了 Stencil 的www构建产物可以被 Vercel 静态托管并正确渲染。

小结

从克隆 Stencil Component Starter、运行开发与构建命令，到理解组件工程结构、遵循命名规范、通过三种策略消费组件，再到在 Vercel 上零配置部署并经过静态构建探针验证——本文以 Vercel 仓库中的 Stencil Component Starter 文档为主线，配合仓库内的组件 fixture 与官方示例，完整覆盖了 Stencil Web Components 从开发到上线的全链路。无论是构建可复用的组件库，还是搭建完整的 Stencil 应用，这套流程都可以直接落地使用。