SST 框架中 "sst is not defined" 错误分析与解决方案

问题现象

在使用 SST（Serverless Stack）框架开发时，开发者可能会遇到一个奇怪的错误提示："✕ Unexpected error occurred. Please check the logs in .sst/log/sst.log"。更令人困惑的是，有时甚至找不到对应的日志文件，导致难以定位问题根源。

错误本质

通过深入分析，我们发现这类错误通常源于 sst.config.ts 配置文件中的引用问题。具体表现为：

1. 在配置文件中尝试使用 new sst.aws... 时抛出 ReferenceError: sst is not defined 错误
2. 类似地，使用 $app. 变量时也可能出现引用错误
3. 错误信息不直接显示在控制台，需要通过 --print-logs 参数才能查看完整错误

问题原因

这种错误通常由以下几个因素导致：

1. 依赖安装不完整：SST 核心包可能没有正确安装或链接
2. 构建缓存问题：之前的构建缓存可能导致模块解析异常
3. 包管理器差异：使用不同包管理器（如 pnpm、bun、npm）时可能产生不一致的依赖关系
4. 环境变量冲突：某些环境变量可能干扰了 SST 的正常加载

解决方案

基础修复步骤

1. 清理项目缓存：

   rm -rf .sst node_modules
   

2. 重新安装依赖：

   bun install  # 或 npm install/yarn/pnpm install
   

3. 运行 SST 安装命令：

   bunx sst install  # 或 npx sst install
   

高级排查技巧

1. 查看详细日志：

   sst dev --print-logs
   

2. 检查包管理器锁定文件：

   • 确保 package-lock.json/yarn.lock/pnpm-lock.yaml 是最新的
   • 考虑删除锁定文件后重新安装

3. 验证 TypeScript 配置：

   • 确保 tsconfig.json 包含正确的模块解析设置
   • 检查是否有任何自定义路径别名干扰了 SST 的导入

4. 环境隔离测试：

   • 在新目录中创建最小化复现项目
   • 使用不同 Node.js 版本测试

最佳实践建议

1. 统一包管理器：在团队中统一使用相同的包管理器（推荐使用项目指定的包管理器）

2. 版本控制：

   • 将 .sst 目录加入 .gitignore
   • 但保留 sst.config.ts 和所有依赖声明

3. 配置验证：

   import { Config } from "sst";
   
   export default {
     // 配置内容
   } satisfies Config;
   

4. 持续集成设置：

   • 在 CI/CD 环境中预先运行 sst install
   • 设置缓存策略时包含 node_modules 但不包含 .sst

技术原理深入

SST 框架在初始化时会动态加载核心模块，这个过程依赖于 Node.js 的模块解析机制。当出现 sst is not defined 错误时，实际上是模块加载链在某个环节中断了。现代包管理器如 pnpm 和 bun 使用非扁平化的 node_modules 结构，这可能在某些情况下导致模块解析路径与预期不同。

在底层，SST 使用了一个内部的模块注册系统，当这个系统初始化失败时，就会抛出这种看似不明确的错误。这也是为什么简单的重新安装依赖往往能解决问题 - 它重建了正确的模块解析路径。

总结

"SST is not defined" 这类错误虽然表象简单，但反映了 JavaScript 生态中模块解析的复杂性。通过系统性地清理缓存、验证依赖完整性、使用正确的调试方法，开发者可以快速解决这类问题。理解背后的模块加载机制也有助于预防类似问题的发生，提高开发效率。