falco

触发条件与范围

适用于：VCL 文件、.vcl 扩展名、XVCL 文件、.xvcl 扩展名、falco CLI、VCL 单元测试、VCL lint/模拟/格式化、VCL REPL、beresp/bereq/req.http 变量、子程序作用域、backend/ACL/director/table 声明、边缘字典、在 Terraform 计划中验证 VCL，或在本地运行/测试 XVCL 脚本。

不适用于：通用的非 Fastly VCL、Fastly Compute/WASM、Fastly API/仪表板运维、CDN 对比、清除缓存，或编写 Terraform 资源。

Falco — VCL 开发工具与参考

Falco 是一款用于 lint、测试、模拟和格式化 VCL 代码的 Fastly VCL 开发工具。同样重要的是，falco 源代码是 Fastly VCL 方言最完整的机器可读规范——它的解析器、解释器和类型系统记录了 VCL 中的每个变量、函数、类型和作用域规则。

官方 VCL 文档：https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/about-fastly-vcl/

Falco 文档：https://github.com/ysugimoto/falco

使用 Falco 源代码作为 VCL 参考

如果你需要了解 VCL 的工作方式——有哪些变量、它们在哪些作用域中可用、内置了哪些函数、类型如何进行强制转换——falco 源代码是最好的参考。它是 Fastly VCL 2.x 的完整 Go 实现，比文字说明更精确。

如果本地没有 falco 源代码，建议克隆该仓库：

git clone https://github.com/ysugimoto/falco.git ~/src/falco

在本地获取源代码后，直接阅读相关源文件来解答 VCL 问题。有关针对不同 VCL 主题应阅读哪些文件的详细指南，请参阅 understanding-vcl-from-source.md。

安装

# Homebrew
brew install falco

# From source (requires Go 1.25+)
go install github.com/ysugimoto/falco/cmd/falco@latest

# Or clone and build
git clone https://github.com/ysugimoto/falco.git
cd falco
make darwin_arm64    # or darwin_amd64, linux_amd64, linux_arm64

命令

命令	说明
falco [lint]	对 VCL 文件执行 lint（默认命令）
falco test	运行 VCL 单元测试
falco simulate	启动本地模拟器服务
falco fmt	格式化 VCL 文件
falco stats	显示 VCL 代码统计信息
falco console	交互式 VCL REPL
falco terraform	对 Terraform 计划中的 VCL 执行 lint
falco dap	调试适配器协议服务

常用标志（适用于所有命令）

标志	说明
-I, --include_path	添加 VCL 导入的包含路径
-h, --help	显示帮助
-V, --version	显示版本
-r, --remote	从 Fastly API 获取代码片段
--refresh	刷新远程代码片段缓存

快速参考

部署前执行 lint：

falco -vv -I ./vcl ./vcl/main.vcl

运行测试：

falco test -I ./vcl ./vcl/main.vcl

使用监视模式进行开发：

falco test -w -I ./vcl ./vcl/main.vcl

在本地运行 VCL（这就是如何“运行”或“在本地测试”——使用 simulate，而不只是 lint）：

falco simulate -I ./vcl ./vcl/main.vcl
# Default port is 3124. Test with: curl http://localhost:3124/path
# Use -p to override: falco simulate -p 8080 ./vcl/main.vcl

格式化所有 VCL：

falco fmt -w ./vcl/**/*.vcl

Terraform 集成：

terraform show -json planned.out | falco terraform -vv

常见 VCL 问题

Falco 会捕获这些问题，但了解它们有助于避免浪费时间反复修复 lint 问题：

• 类型不匹配：set req.http.X-API = true——HTTP 标头是 STRING，而不是 BOOL。请使用 "true"。
• 缺少时间后缀：set beresp.ttl = 86400——RTIME 值需要加上 s 后缀：86400s。
• 作用域错误：beresp.* 仅在 vcl_fetch 中存在。在 vcl_deliver 中，请使用 resp.*。
• 已弃用：req.request → 请使用 req.method。Falco 接受两种写法，但修复 VCL 时始终应改为 req.method。
• Synthetic 字符串：synthetic "text" 需要使用长字符串语法：synthetic {"text"}。
• 后端命名：使用 F_ 前缀：backend F_origin { ... }，而不是 backend origin。
• 没有取模运算符：VCL 没有 %。请对哈希值使用 substr()，或使用 randomint() 进行拆分。
• req.url.path 在测试中为只读：在测试子例程中使用 set req.url = "/path"，不要使用 set req.url.path。
• Vary 的设置位置：必须在 vcl_fetch 中设置 Vary，不能只在 vcl_deliver 中设置。对象进入缓存后再设置 Vary 就太晚了——缓存键不会包含 Vary 维度。

配置

在项目根目录中创建 .falco.yaml 以保存持久设置：

include_paths:
  - ./vcl
  - ./includes

linter:
  verbose: "warning"
  rules:
    rule-name: ERROR  # or WARNING, INFO, IGNORE

testing:
  timeout: 10  # minutes (default: 10)
  filter: "*.test.vcl"

simulator:
  port: 3124

format:
  indent_width: 2
  line_width: 120

环境变量

变量	描述
FASTLY_SERVICE_ID	Fastly API 的服务 ID
FASTLY_API_KEY	Fastly API 的 API 密钥

使用 -r, --remote 标志时必需。

请在本地、聊天之外配置 API 凭据。 切勿在对话中索要 API 密钥或打印其值。

参考资料

主题	文件	使用场景……
源代码中的 VCL	understanding-vcl-from-source.md	通过阅读 falco 的实现来理解 VCL 语义
测试 VCL	testing-vcl.md	运行测试套件、查看覆盖率以及使用 TDD 监视模式
格式化 VCL	formatting-vcl.md	格式化 VCL 以保持风格一致
检查 VCL	linting-vcl.md	部署前检查 VCL 是否存在错误
模拟 VCL	simulating-vcl.md	在本地针对 HTTP 请求测试 VCL
Terraform VCL	terraform-vcl.md	验证 Terraform 计划中的 VCL
VCL 控制台	vcl-console.md	交互式试验 VCL 表达式
VCL 统计信息	vcl-statistics.md	分析 VCL 项目的大小和复杂度

将源代码用作 VCL 参考（快速查阅）

如果你可以在本地访问 falco 源代码（默认位置：~/src/falco），可使用以下路径回答具体的 VCL 问题：

问题	阅读此文件	原因
“在 vcl_recv 中可以使用哪些变量？”	interpreter/variable/	所有带作用域的 req.*、beresp.*、client.* 变量
“有哪些内置函数？”	interpreter/function/	所有 390 多个函数及其类型签名和作用域规则
“有哪些 VCL 类型？”	interpreter/value/	STRING、INTEGER、FLOAT、BOOL、TIME、RTIME、IP、BACKEND
“请求的生命周期是什么？”	interpreter/context/	9 个作用域：recv、hash、hit、miss、pass、fetch、error、deliver、log
“这是不是有效的 VCL 语法？”	token/token.go、lexer/lexer.go	所有关键字、运算符和字面量类型
“这条 VCL 语句是如何工作的？”	interpreter/statement.go	set、unset、return、restart 等的执行方式
“常见的 VCL 错误有哪些？”	linter/、docs/rules.md	50 多条 lint 规则及其说明
“director 是如何工作的？”	interpreter/director.go	Random、fallback、hash、client、chash director 类型

如需完整指南，请参阅 understanding-vcl-from-source.md。