Preflight.sh

Preflight.sh 是一个命令行工具，用于扫描你的代码库，检查上线就绪状态。它能在你部署到生产环境之前，识别缺失的配置、集成问题、安全隐患、SEO 元数据缺口以及其他常见错误。

别在生产环境丢人现眼。直接运行命令即可。

安装

Homebrew (macOS/Linux)

brew install preflightsh/preflight/preflight

npm

npm install -g @preflightsh/preflight

Go

go install github.com/preflightsh/preflight@latest

Docker

docker pull ghcr.io/preflightsh/preflight

Shell 脚本

curl -sSL https://preflight.sh/install.sh | sh

手动下载

从 GitHub Releases 下载最新版本。

快速开始

# 在你的项目目录中初始化
cd your-project
preflight init

# 运行所有检查
preflight scan

# 扫描指定目录
preflight scan /path/to/project

# 使用详细输出运行（显示每个检查匹配了哪些文件）
preflight scan --verbose
preflight scan -v  # 简写形式

# 以 CI 模式运行并输出 JSON
preflight scan --ci --format json

# 只运行特定检查，或跳过某些检查，以便快速迭代
# （一次性操作；与 `preflight ignore` 不同，它不会修改 preflight.yml）
preflight scan --only seo_meta,og_twitter
preflight scan --skip vulnerability,secrets

# 静默某个检查
preflight ignore sitemap

# 取消静默某个检查
preflight unignore sitemap

# 列出所有检查 ID
preflight checks

Agent 技能

本仓库包含一个兼容 skills.sh 的 agent 技能，位于 skills/preflight/SKILL.md。它为编码 agent 提供了一个可重复的 Preflight 工作流程：检查 preflight.yml、运行 CI 安全扫描、对发现结果进行分类、避免不安全的忽略操作、重新运行验证，并报告剩余的发布风险。

从本仓库列出该技能：

# 使用 Bun
bunx --yes skills add preflightsh/preflight --list

# 或使用 npm
npx --yes skills add preflightsh/preflight --list

仅安装 Preflight 技能：

# 使用 Bun
bunx --yes skills add preflightsh/preflight --skill preflight

# 或使用 npm
npx --yes skills add preflightsh/preflight --skill preflight

仪表盘与 AI 建议

Preflight 无需账户即可在命令行中完全使用。可选的仪表盘位于 app.preflight.sh，它提供扫描历史记录以及针对每项发现的 AI 生成的修复建议。你的代码永远不会离开你的机器：扫描在本地运行，只有经过脱敏的结果摘要（检查 ID、状态和消息，绝不包含密钥值或文件内容）会在你发布时被发送。

创建一个免费账户，然后连接 CLI：

preflight auth login    # 打开浏览器以授权此 CLI
preflight auth status   # 显示当前登录用户
preflight auth logout   # 删除已存储的凭据

使用 --publish 将扫描发布到你的仪表盘。它会打印一个链接以查看运行结果。发布是尽力而为的：如果你处于离线状态或未登录，扫描仍会运行并正常退出。

preflight scan --publish

在仪表盘上，你可以看到每次运行的通过/警告/失败统计、完整的发现列表，以及按项目划分的历史记录，从而了解两次部署之间发生了什么变化。

你也可以通过 preflight history 在终端中读取该历史记录：

preflight history                       # 你所有项目中最近的运行记录
preflight history --here                # 仅当前项目的运行记录
preflight history <run-id>              # 单次运行的完整检查结果
preflight history --here --format json  # 机器可读格式，供 agent 使用

需要先执行 preflight auth login。--here 通过 git remote 将运行记录与当前仓库匹配，这与发布时使用的键相同。

打开已发布运行中的任何失败或警告检查，即可生成针对你检测到的技术栈量身定制的分步修复方案，其中包含可直接复制的命令和代码。

• 免费版 每月包含 5 次已发布的运行。
• 自带密钥： 在仪表盘设置中添加 OpenAI 或 Anthropic API 密钥，发布将保持免费且无限制（你直接向提供商付费）。
• 托管版（每月 $5）： 我们承担 AI 成本，运行次数无限制，无需 API 密钥。

检查内容

支持的服务（72 项）

Preflight 会自动检测并验证以下服务的配置：

支付

• Stripe、PayPal、Braintree、Paddle、LemonSqueezy

错误跟踪与监控

• Sentry、Bugsnag、Rollbar、Honeybadger、Datadog、New Relic、LogRocket

邮件与通讯

• Postmark、SendGrid、Mailgun、AWS SES、Resend、Mailchimp、Kit、Beehiiv、AWeber、ActiveCampaign、Campaign Monitor、Drip、Klaviyo、Buttondown

分析

• Plausible、Fathom、Umami、Fullres Analytics、Datafa.st Analytics、Google Analytics、PostHog、Mixpanel、Amplitude、Segment、Hotjar

认证

• Auth0、Clerk、WorkOS

聊天

• Intercom、Crisp

通知

• Slack、Discord、Twilio

基础设施

• Firebase、Supabase、Redis、Sidekiq、RabbitMQ、Elasticsearch、Convex

存储与 CDN

• AWS S3、Cloudinary、Cloudflare

搜索

• Algolia

SEO

• IndexNow

AI / LLM

• OpenAI、Anthropic Claude、Google AI (Gemini)、Mistral、Cohere、Replicate、Hugging Face、Grok (X/Twitter)、Perplexity、Together AI

配置

Preflight 使用项目根目录下的 preflight.yml 文件：

projectName: my-app
stack: rails  # rails, next, react, vite, laravel, etc.

urls:
  staging: "https://staging.example.com"
  production: "https://example.com"

services:
  stripe:
    declared: true
  sentry:
    declared: true

checks:
  envParity:
    enabled: true
    envFile: ".env"
    exampleFile: ".env.example"

  healthEndpoint:
    enabled: true
    path: "/health"  # 可选 - 未设置时自动检测常见路径

  stripeWebhook:
    enabled: true
    url: "https://api.example.com/webhooks/stripe"  # 可选 - 使用 GET 探测；404 或无响应会被报告

  seoMeta:
    enabled: true
    mainLayout: "app/views/layouts/application.html.erb"

  security:
    enabled: true

  secrets:
    enabled: true
    # 密钥扫描的按文件白名单。用于抑制单个
    # 发现（例如受 referrer 限制的公钥），而无需
    # 禁用整个检查。
    allowlist:
      - path: web/js/golden-hour.js
        fingerprint: "sha256:<hex>"   # 推荐 — 精确定位到具体密钥
        reason: "受 HTTP referrer 限制的 Google Timezone 密钥"
      - path: "web/tools/**/*.php"    # 支持 doublestar glob 模式

  indexNow:
    enabled: true
    key: "your32characterhexkeyhere00000"

  emailAuth:
    enabled: true  # 可选，检查生产域名的 SPF/DMARC

  humansTxt:
    enabled: false  # 可选，表彰团队

  license:
    enabled: false  # 可选，适用于开源项目

# 按 ID 静默特定检查或服务
ignore:
  - sitemap
  - llms_txt
  - google_analytics

忽略检查与服务

使用 preflight ignore <id> 静默特定检查或服务：

preflight ignore sitemap        # 忽略 sitemap 检查
preflight ignore sentry         # 忽略 Sentry 服务验证
preflight unignore sitemap      # 重新启用 sitemap 检查
preflight checks                # 列出所有可忽略的 ID

白名单单个密钥发现

优先对单个发现进行白名单处理，而不是静默整个 secrets 检查。从命令行添加一次性例外：

preflight ignore secrets web/js/golden-hour.js

这会在你的 preflight.yml 中的 checks.secrets.allowlist 下追加一个路径条目。path 字段是一个 doublestar glob 模式（** 可跨目录匹配），相对于项目文件路径进行解析。

固定指纹。 仅包含路径的白名单会静默接受该文件中任何未来出现的密钥。编辑该条目并添加 fingerprint: "sha256:<hex>" — 即检测到的密钥值的 SHA-256。这样，如果密钥被轮换或同一文件中出现不同的密钥，preflight 会重新发出警报。

发现结果按 路径 + 指纹 匹配，而非整个文件。文件中白名单化的指纹不会抑制同一文件中其他行上的其他密钥。

可忽略的检查 ID

SEO 与社交： seo_meta、canonical、structured_data、index_now（可选）、og_twitter、viewport、lang

安全与基础设施： security_headers、ssl、www_redirect、email_auth（可选）、secrets

环境与健康： env_parity、health_endpoint

代码质量与性能： vulnerability、debug_statements、error_pages、image_optimization

法律与合规： legal_pages

Web 标准文件： favicon、robots_txt、sitemap、llms_txt、ads_txt（可选）、humans_txt（可选）、license（可选）

0.22 版本中重命名的检查 ID

现在每个检查 ID 都采用 snake_case。旧的 camelCase 名称在 1.x 系列中仍可在任何接受 ID 的地方使用（ignore: 列表、--only、--skip、preflight ignore），并会在 stderr 上输出提示，在 2.0 中将被移除。preflight ignore 会写入新名称。preflight.yml 中 checks: 下的键（healthEndpoint、seoMeta 等）是独立的 schema，未发生变化。

关于扫描你不信任的代码的说明

每个检查都会读取文件；其中一个会运行程序。vulnerability 检查会在项目目录内执行项目自身的包管理器（npm audit、yarn audit、composer audit、bundle audit、pip-audit、govulncheck、cargo audit），并使用经过清理的环境和临时主目录，因此它无法读取你的令牌。包管理器仍会遵循项目本地配置，其中某些配置可以运行仓库中的代码（Yarn 的 yarnPath、Cargo 别名、Composer 插件）。扫描你自己的项目正是 Preflight 的用途。当扫描你不信任的仓库时（例如 CI 中某个 fork 的拉取请求），请添加 --skip vulnerability。

可忽略的服务 ID

所有服务都有验证检查，用于确认正确的集成（环境变量、SDK 模式、配置文件）：

支付： stripe、paypal、braintree、paddle、lemonsqueezy

错误跟踪： sentry、bugsnag、rollbar、honeybadger、datadog、newrelic、logrocket

事务性邮件： postmark、sendgrid、mailgun、aws_ses、resend

邮件营销： mailchimp、convertkit、beehiiv、aweber、activecampaign、campaignmonitor、drip、klaviyo、buttondown

分析： plausible、fathom、google_analytics、fullres、datafast、posthog、mixpanel、amplitude、segment、hotjar

认证： auth0、clerk、workos、firebase、supabase

通信： twilio、slack、discord、intercom、crisp

基础设施： redis、sidekiq、rabbitmq、elasticsearch、convex

存储与 CDN： aws_s3、cloudinary、cloudflare

搜索： algolia

AI： openai、anthropic、google_ai、mistral、cohere、replicate、huggingface、grok、perplexity、together_ai

SEO： index_now

Cookie 同意： cookieconsent、cookiebot、onetrust、termly、cookieyes、iubenda

退出代码

代码 1 和 2 表示扫描已运行并报告了某些内容。代码 64 表示扫描从未到达该阶段，因此 CI 可以区分"此项目存在问题"和"此调用方式有误"。

Shell 补全

为命令、标志和检查 ID（包括 --only 和 --skip 的值）提供 Tab 补全：

# bash（添加到 ~/.bashrc）
source <(preflight completion bash)

# zsh（添加到 ~/.zshrc）
source <(preflight completion zsh)

# fish
preflight completion fish | source

输出同样遵循 NO_COLOR 环境变量。

支持的技术栈

后端框架

• Ruby on Rails、Laravel、PHP、Go、Python/Django、Rust、Node.js

前端框架

• Next.js、Nuxt、Remix、React、Vue.js、Vite、Svelte、Angular

传统 CMS

• WordPress、Craft CMS、Drupal、Ghost

静态站点生成器

• Hugo、Jekyll、Gatsby、Eleventy (11ty)、Astro

无头 CMS

• Strapi、Sanity、Contentful、Prismic

其他

• 静态站点

CI 集成

# GitHub Actions 示例（curl）
- name: Run Preflight
  run: |
    curl -sSL https://preflight.sh/install.sh | sh
    preflight scan --ci --format json

# GitHub Actions 示例（Docker）
- name: Run Preflight
  run: docker run -v ${{ github.workspace }}:/app ghcr.io/preflightsh/preflight scan --ci --format json

许可证

MIT