把 Vue 3 项目 build 出来的 dist 目录扔到服务器上，这件事本身不难，难的是支撑它的那一整套东西：对象存储桶、CDN 域名、HTTPS 证书、缓存策略，这些云上资源如果全靠控制台手动点出来，环境一多必然乱套。Terraform 的思路是把基础设施也当成代码来管理，写一份配置文件，执行一条命令，资源就能被可重复地创建、修改和销毁。对一个持续迭代的前端项目来说，这套模式带来的可追溯性和一致性，远比省下的那几次点击更有价值。
为什么前端项目也需要基础设施即代码
传统认知里 Terraform 是后端或运维的工具，和前端关系不大。但实际场景中，一个 Vue 3 应用从开发到上线涉及的基础设施并不少：静态资源要放到 OSS 或 S3 这类对象存储，用户访问要走 CDN 加速，自定义域名要绑定 HTTPS 证书，缓存规则要根据文件名 hash 做区分。这些配置项分散在云控制台的各个角落，一旦需要搭建测试、预发、生产多套环境，手动操作的出错概率会成倍上升。
基础设施即代码（IaC）解决的核心问题是“环境的可复现性”。Terraform 使用 HCL 语言描述资源的期望状态，执行terraform apply之后，Terraform 会对比当前云上的实际状态和配置文件中的期望状态，自动计算出需要创建、修改还是删除哪些资源。这意味着新成员入职时不再需要一份过时的部署文档，只需要拿到代码仓库和云账号权限，就能一键拉起一套完全一致的环境。
另一个常被忽视的好处是变更审计。所有基础设施改动都以代码提交的形式记录在 Git 历史里，谁在什么时候改了 CDN 的缓存规则，一查便知。出了线上问题需要回滚时，git revert 配合一次 apply 就能恢复到之前的基础设施状态，这比在控制台里凭记忆找配置靠谱得多。
Terraform 核心概念速览
在动手之前，先理清几个绕不开的概念。第一个是 provider，也就是云厂商插件。Terraform 本身不认识阿里云、AWS 还是腾讯云，它通过 provider 插件与各家云的 API 通信。声明 provider 时需要指定地域和认证信息，认证凭据建议通过环境变量注入而不是写进代码。
第二个是 state 状态文件。Terraform 会把每次 apply 后的资源信息记录在一个 JSON 格式的 state 文件里，下次执行时靠它来判断哪些资源已经存在。state 文件非常关键，丢了就等于失去了对已建资源的管理能力。团队协作时必须把 state 放到远程后端，比如对象存储加锁机制，避免两个人同时 apply 造成状态冲突。
第三个是 module 模块。当测试、预发、生产三套环境结构相同只是参数不同时，把资源定义抽成模块，每个环境只传一组变量进去，就能避免大段复制粘贴。模块化是 Terraform 项目保持可维护性的关键手段，下文的完整示例会体现这一点。
为 Vue 3 项目搭建 Terraform 工程结构
先规划目录结构。一个比较稳妥的组织方式是把基础设施代码放在项目内的 infrastructure 目录，或者干脆独立一个仓库。这里以放在同一仓库为例，目录结构如下：
vue3-app/ ├── src/ ├── infrastructure/ │ ├── modules/ │ │ └── static-site/ # 静态站点模块 │ │ ├── main.tf │ │ ├── variables.tf │ │ └── outputs.tf │ ├── environments/ │ │ ├── staging/ │ │ │ └── main.tf # 预发环境入口 │ │ └── production/ │ │ └── main.tf # 生产环境入口 │ └── backend.tf # state 远端存储配置
先看模块定义。static-site 模块负责创建对象存储桶和 CDN，把可变的部分全部通过变量暴露出去：
# modules/static-site/variables.tf
variable "env" {
description = "环境标识，用于资源命名"
type = string
}
variable "domain" {
description = "站点绑定的自定义域名"
type = string
}
variable "bucket_name" {
description = "对象存储桶名称"
type = string
}
资源主体写在 main.tf 中，以阿里云为例创建 OSS 桶并配置为静态网站托管模式，index 文档指向 index.html，错误文档也指向 index.html 以支持 Vue Router 的 history 路由模式，避免刷新页面时出现 404：
# modules/static-site/main.tf
resource "alicloud_oss_bucket" "site" {
bucket = var.bucket_name
website {
index_document = "index.html"
error_document = "index.html"
}
# 简单上传权限，供 CI 推送构建产物
acl = "public-read"
}
resource "alicloud_cdn_domain_new" "site" {
domain_name = var.domain
cdn_type = "web"
scope = "overseas"
sources {
content = "${var.bucket_name}.oss-cn-hangzhou.aliyuncs.com"
type = "oss"
priority = "20"
weight = "10"
}
}
output "bucket_domain" {
value = alicloud_oss_bucket.site.intranet_endpoint
}
环境入口文件则非常薄，只负责调用模块并传入参数。生产环境可以多加一层 CDN 或者开启更长的缓存时间，这都属于变量层面的差异：
# environments/production/main.tf
module "static_site" {
source = "../../modules/static-site"
env = "prod"
domain = "www.example.cn"
bucket_name = "vue3-prod-static"
}
state 远端存储建议尽早配置，尤其是多人协作时。以 OSS 作为后端的写法如下，开启 state 加锁可以防止并发 apply：
# backend.tf
terraform {
required_version = ">= 1.5.0"
backend "oss" {
bucket = "tf-state-lock-bucket"
prefix = "vue3-app/production"
encrypt = true
}
required_providers {
alicloud = {
source = "aliyun/alicloud"
version = "~> 1.210.0"
}
}
}
接入 CI 流水线实现一键部署
基础设施代码写好后，接下来把它和 Vue 3 的构建流程串起来。思路是分两条路径：基础设施变更走手动审批的 workflow，前端代码发布走自动触发的 workflow。这样日常迭代只上传 dist 产物，不动 Terraform；而 CDN 规则调整这类低频操作单独走受控流程。
前端自动部署的 workflow 比较直接，先 build 再用 ossutil 同步产物，同步完成后刷新 CDN 缓存让新版本立即生效：
name: deploy-frontend
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci && npm run build
- name: 上传构建产物
run: |
wget -q https://gosspublic.alicdn.com/ossutil/ossutil64
chmod +x ossutil64
./ossutil64 cp -rf dist/ oss://vue3-prod-static/ \
-e ${{ secrets.OSS_ENDPOINT }} \
-i ${{ secrets.OSS_KEY_ID }} \
-k ${{ secrets.OSS_KEY_SECRET }}
- name: 刷新 CDN 缓存
run: |
curl -s "https://cdn.ipipp.com/refresh?url=https://www.example.cn/" \
-H "Authorization: Bearer ${{ secrets.CDN_TOKEN }}"
基础设施 workflow 则要求 pull request 触发时自动执行terraform plan并把执行计划以评论形式贴到 PR 里，人工确认计划无误后再手动触发terraform apply。这种 plan 与 apply 分离的模式是社区公认的最佳实践，能最大限度避免误操作把生产资源删掉。
有两点细节值得注意。一是 Vite 构建的静态资源文件名自带 hash，可以把 CDN 缓存时间设得非常长，比如一年，而 index.html 因为不带 hash 必须设置短缓存或不缓存，否则用户会长时间停留在旧版本。二是 Terraform 的 apply 操作要限制执行权限，建议通过 GitHub Environments 的保护规则指定允许执行的分支和审批人。
常见坑与应对经验
第一个大坑是 state 文件损坏或丢失。state 存在本地机器上是最危险的做法，机器故障或者目录误删，云上的资源就成了无人认领的孤儿。务必从第一天起就用远端后端，并且开启版本化存储，这样即使 state 被错误修改也能回滚到历史版本。如果资源已经失控，可以通过terraform import把存量资源重新导入 state，虽然过程繁琐但比重建资源好得多。
第二个坑是密钥泄露。AccessKey 绝对不能硬编码在 .tf 文件里，即便提交到私有仓库也存在风险。正确做法是本地开发用环境变量，CI 环境用平台的 secrets 机制。另外可以在 .gitignore 里显式忽略.terraform目录和所有.tfstate文件，做双重保险。
第三个坑是多环境隔离不彻底。有人图省事用同一个 state 文件管理测试和生产，结果一次针对测试环境的变更误伤了生产资源。正确的隔离粒度是每个环境独立的 state 目录、独立的变量文件，甚至独立的云账号。虽然前期配置多花点时间，但当某个环境需要做破坏性实验时，你会感谢当初的隔离决策。配合 Vue 3 项目本身的多模式构建（比如 .env.production 和 .env.staging），前端代码与基础设施在环境维度上也能对齐，整条交付链路就真正闭环了。