SST项目在Vercel上部署Astro应用的环境变量问题解决方案

背景介绍

在使用SST（Serverless Stack Toolkit）结合Vercel部署Astro静态站点时，开发者可能会遇到一个常见问题：应用在本地开发环境运行正常，但在Vercel上部署后出现"SST links are not active"的错误提示。这个问题源于SST的资源链接机制在Vercel平台上无法正常工作。

问题分析

SST框架通过sst shell命令为应用注入必要的环境变量，这些变量通常以SST_RESOURCE_为前缀。在AWS环境下，SST会自动处理这些变量的注入，但在Vercel平台上，这一机制需要手动实现。

当应用在Vercel上运行时，中间件（构建为Lambda函数）执行时缺少了sst shell注入的环境变量，导致应用无法正确识别SST资源链接，从而抛出错误。

解决方案

方案一：手动传递环境变量

开发者可以手动将sst shell生成的环境变量转换为Vercel项目环境变量：

1. 遍历所有sst.Secret资源
2. 为每个资源创建对应的vercel.ProjectEnvironmentVariable
3. 确保变量名以SST_RESOURCE_开头

这种方法虽然可行，但维护成本较高，特别是当项目中有大量SST资源时。

方案二：创建Astro集成插件

更优雅的解决方案是创建一个Astro集成插件，自动处理环境变量的注入。以下是实现步骤：

1. 在astro.config.ts中引入自定义插件
2. 插件通过Astro的生命周期钩子获取Vercel函数配置
3. 在构建完成后修改.vc-config.json文件，注入必要的环境变量

import type { AstroIntegration } from "astro";
import * as fs from "node:fs";

export const sst = (): AstroIntegration => {
  let vcConfig: URL;

  return {
    name: "sst",
    hooks: {
      "astro:config:done": async ({ config, logger }) => {
        vcConfig = new URL(
          ".vercel/output/functions/_render.func/.vc-config.json",
          config.root
        );
      },
      "astro:build:done": async ({ logger }) => {
        const vcConfigJson = JSON.parse(fs.readFileSync(vcConfig, "utf8"));
        
        vcConfigJson.environment = {
          ...vcConfigJson.environment,
          ...Object.fromEntries(
            Object.entries(process.env).filter(([key]) => {
              if (key.startsWith("SST_RESOURCE_")) {
                logger.info(`Injecting ${key} to .vc-config.json`);
                return true;
              }
            })
          ),
        };

        fs.writeFileSync(vcConfig, JSON.stringify(vcConfigJson, null, 2));
      },
    },
  };
};

实现原理

该解决方案利用了Astro的集成系统，通过以下机制工作：

1. 配置阶段：获取Vercel函数配置文件的路径
2. 构建完成阶段：读取并修改Vercel函数配置
3. 环境变量注入：筛选所有SST_RESOURCE_开头的环境变量并注入到配置中

这种方法确保了在Vercel平台上运行时，应用能够访问到与本地开发环境相同的SST资源链接。

最佳实践建议

1. 环境变量管理：建议将敏感信息存储在SST的Secret资源中，而不是直接硬编码
2. 构建脚本：确保package.json中的构建脚本正确使用sst shell包装命令
3. 测试验证：在部署前，验证环境变量是否被正确注入到构建产物中
4. 日志监控：添加适当的日志输出，便于调试环境变量注入过程

未来改进方向

虽然当前解决方案有效，但从长远来看，SST项目可以考虑：

1. 提供官方Vercel适配器，类似现有的AWS适配器
2. 开发专门的@astrojs/sst-vercel集成包
3. 改进文档，提供多平台部署的详细指南

通过上述解决方案，开发者可以顺利地在Vercel平台上部署基于SST的Astro应用，同时保持与本地开发环境一致的资源链接行为。