Preflight.sh

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

不要在生产环境出丑。只需运行命令即可。

Installation

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 Script

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

Manual Download

Download the latest release from GitHub Releases.

Quick Start

# Initialize in your project directory
cd your-project
preflight init

# Run all checks
preflight scan

# Scan a specific directory
preflight scan /path/to/project

# Run with verbose output (shows which files matched each check)
preflight scan --verbose
preflight scan -v  # short form

# Run in CI mode with JSON output
preflight scan --ci --format json

# Run only specific checks, or skip some, for fast iteration
# (one-off; unlike `preflight ignore` it doesn't change preflight.yml)
preflight scan --only seoMeta,ogTwitter
preflight scan --skip vulnerability,secrets

# Silence a check
preflight ignore sitemap

# Unsilence a check
preflight unignore sitemap

# List all check IDs
preflight checks

Agent Skill

此仓库包含一个兼容 skills.sh 的 Agent 技能，位于 skills/preflight/SKILL.md。它为编码智能体提供了一个可重复执行的 Preflight 工作流：检查 preflight.yml、运行 CI 安全扫描、分类处理发现的问题、避免不安全的忽略、重新运行验证，并报告剩余的上线风险。

从该仓库列出技能：

# With Bun
bunx --yes skills add preflightsh/preflight --list

# Or with npm
npx --yes skills add preflightsh/preflight --list

仅安装 Preflight 技能：

# With Bun
bunx --yes skills add preflightsh/preflight --skill preflight

# Or with npm
npx --yes skills add preflightsh/preflight --skill preflight

Dashboard & AI Suggestions

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

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

preflight auth login    # opens your browser to authorize this CLI
preflight auth status   # show who you're logged in as
preflight auth logout   # remove stored credentials

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

preflight scan --publish

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

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

preflight history                       # recent runs across your projects
preflight history --here                # only the current project's runs
preflight history <run-id>              # one run's full check results
preflight history --here --format json  # machine-readable, for agents

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

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

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

What It Checks

Check	Description
ENV Parity	比较 `.env` 和 `.env.example`，查找缺失的变量
Health Endpoint	验证站点是否可访问；自动检测 `/health`、`/healthz`、`/api/health`，否则回退到根路径
Vulnerability Scan	检查依赖漏洞（bundle audit、npm audit 等）
SEO Metadata	检查 title、description 和 Open Graph 标签
OG & Twitter Cards	验证 og:image、twitter:card 和社交分享元数据
Canonical URL	验证 canonical 链接标签是否存在
Viewport	检查移动端 viewport meta 标签是否正确
Lang Attribute	验证 html lang 属性以确保无障碍访问
Structured Data	检查 JSON-LD Schema.org 标记
Security Headers	在生产环境和预发布环境验证 HSTS、CSP、X-Content-Type-Options
SSL Certificate	检查 SSL 有效性并在过期前发出警告
WWW Redirect	验证 www/非 www 是否重定向到 canonical URL
Email Auth	检查 SPF/DMARC DNS 记录以确保邮件送达率（可选）
Secret Scanning	发现代码中泄露的 API 密钥和凭据
Debug Statements	检测代码中遗留的 console.log、var_dump、debugger
Error Pages	检查自定义 404/500 错误页面
Image Optimization	发现影响加载时间的大图片（>500KB）
Legal Pages	检查隐私政策和服务条款页面
Cookie Consent	检测 Cookie 同意解决方案（GDPR/CCPA 合规性）
Favicon & Icons	检查 favicon、apple-touch-icon（.png、.webp、.svg）和 web manifest
robots.txt	验证 robots.txt 是否存在且包含内容
sitemap.xml	检查 sitemap 是否存在或其生成器
llms.txt	检查 LLM 爬虫指南文件
ads.txt	验证广告支持站点的 ads.txt（可选）
humans.txt	检查 humans.txt 以对团队致谢（可选）
IndexNow	验证 IndexNow 密钥文件以加快搜索引擎索引（可选）
LICENSE	检查许可证文件（可选，适用于开源项目）

Supported Services (72)

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

Payments

Stripe, PayPal, Braintree, Paddle, LemonSqueezy

Error Tracking & Monitoring

Sentry, Bugsnag, Rollbar, Honeybadger, Datadog, New Relic, LogRocket

Email & Newsletters

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

Analytics

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

Auth

Auth0, Clerk, WorkOS

Chat

Intercom, Crisp

Notifications

Slack, Discord, Twilio

Infrastructure

Firebase, Supabase, Redis, Sidekiq, RabbitMQ, Elasticsearch, Convex

Storage & CDN

AWS S3, Cloudinary, Cloudflare

Search

Algolia

SEO

IndexNow

AI / LLMs

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

Configuration

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"  # optional - auto-detects common paths if not set

  stripeWebhook:
    enabled: true
    url: "https://api.example.com/webhooks/stripe"

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

  security:
    enabled: true

  secrets:
    enabled: true
    # Per-file allowlist for the secrets scan. Use this to suppress an
    # individual finding (e.g. a referrer-restricted public key) without
    # disabling the whole check.
    allowlist:
      - path: web/js/golden-hour.js
        fingerprint: "sha256:<hex>"   # recommended — pins to the exact secret
        reason: "HTTP-referrer-restricted Google Timezone key"
      - path: "web/tools/**/*.php"    # doublestar globs are supported

  indexNow:
    enabled: true
    key: "your32characterhexkeyhere00000"

  emailAuth:
    enabled: true  # opt-in, checks SPF/DMARC on production domain

  humansTxt:
    enabled: false  # opt-in, credits the team

  license:
    enabled: false  # opt-in, for open source projects

# Silence specific checks or services by ID
ignore:
  - sitemap
  - llmsTxt
  - google_analytics

Ignoring Checks & Services

使用 preflight ignore <id> 忽略特定的检查或服务：

preflight ignore sitemap        # Ignore sitemap check
preflight ignore sentry         # Ignore Sentry service validation
preflight unignore sitemap      # Re-enable sitemap check
preflight checks                # List all ignorable IDs

Allowlisting a single secrets finding

与禁用整个 secrets 检查相比，更推荐为单个发现添加白名单。可以通过命令行添加一次性例外：

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

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

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

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

Ignorable Check IDs

SEO 与社交： seoMeta, canonical, structured_data, indexNow (opt-in), ogTwitter, viewport, lang

安全与基础设施： securityHeaders, ssl, www_redirect, email_auth (opt-in), secrets

环境与健康： envParity, healthEndpoint

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

法律与合规： legal_pages

Web 标准文件： favicon, robotsTxt, sitemap, llmsTxt, adsTxt (opt-in), humansTxt (opt-in), license (opt-in)

Ignorable Service IDs

所有服务都有验证检查，用于确认集成的正确性（环境变量、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： indexNow

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

Exit Codes

Code	Meaning
0	所有检查均通过
1	仅警告
2	发现错误
64	Preflight 无法运行（路径错误、配置无法读取、未知的检查 ID）
130	扫描已取消（Ctrl-C / SIGTERM）

退出码 1 和 2 表示扫描已运行并报告了某些内容。退出码 64 表示扫描从未运行到那一步，因此 CI 可以区分“这个项目存在问题”和“这次调用有误”。

Shell Completions

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

# bash (add to ~/.bashrc)
source <(preflight completion bash)

# zsh (add to ~/.zshrc)
source <(preflight completion zsh)

# fish
preflight completion fish | source

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

Supported Stacks

后端框架

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

其他

Static sites

CI Integration

# GitHub Actions example (curl)
- name: Run Preflight
  run: |
    curl -sSL https://preflight.sh/install.sh | sh
    preflight scan --ci --format json

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

License

MIT