全栈工程师 | SSG：团队协作

▌ 技术引导 我见过很多全栈工程师在SSG项目里翻车，关键问题集中在部署流程和环境隔离不够精细上。SSG项目本该是前端和后端分离的典范，但很多人在部署时没意识到静态生成和动态服务的耦合点，导致版本混乱、依赖冲突、构建失败。我用过的最稳定方案是结合Vercel的预设环境和Docker的镜像打包，两者配合能避免大部分踩坑。其次是环境变量管理，我用过Vault和AWS Secrets Manager，但最直接的是Vercel的env变量和Git的secret管理工具。在部署脚本里，我强制要求使用CI/CD流水线，不允许手动push到生产环境。SSG项目的核心是构建流程自动化，而不是手动操作。 构建过程中，我常遇到静态资源路径错误，尤其是路径拼接和CDN缓存策略不一致。这时候必须用Vercel的`outputDirectory`配置指定静态文件输出路径，同时设置`routes`规则确保HTTP重定向正确。某个项目因为没设置`headers`，导致静态资源被浏览器缓存到错误位置，反复清理缓存都没解决，最后发现是`fetch`请求头没加`Cache-Control: no-cache`。还有人用`gatsby-plugin-image`时，没配置`gatsby-config.js`里的`gatsby-plugin-image`和`gatsby-plugin-sitemap`，导致图片懒加载失败，SEO也出问题。我踩过这些坑，所以现在写部署脚本时会强制检查这些配置项。 在SSG项目里，团队协作是最容易崩溃的地方，尤其是多人同时修改构建配置。我用过GitHub Actions，但发现分支保护规则不完善，导致主分支被误提交。后来改用Git Hooks的`pre-commit`和`pre-push`，结合ESLint和Prettier自动校验代码风格和格式，避免提交前出错。还有人用Vercel的`vercel.json`来管理多个环境，但我发现配置项没写清楚，导致构建时不知道用哪个环境变量。最终我改用YAML文件配合CI/CD，更清晰易维护。 部署时遇到服务器资源不足的问题，我直接用`pm2`管理Node.js服务，配置了`--no-daemon`和`--min-memory`参数，确保服务不会占用过多内存。另一个问题是在微服务架构下，SSG项目和API服务需要独立部署，但很多人把它们混在一起，导致调试困难。我用过Vercel和Netlify的API部署，不过发现它们对Node.js的版本支持有限，最后转用自托管的Docker镜像，配合Kubernetes做负载均衡，效果更好。 团队里有时候会因为构建输出的格式不一致，导致部署失败，我特意写了一个`build-checker`脚本，在CI阶段自动检查`dist`文件夹结构是否符合预期，同时校验`index.html`里的``是否正确。我还遇到过构建任务依赖其他服务，比如数据库或配置中心，但没设置正确的等待时间，导致部署时服务未就绪。解决方法是用`wait-for-it.sh`脚本等待端口开放，再触发构建任务，这样能避免连不上数据库的问题。 ▌ 技术参考 一 技术背景与核心概念 SSG（Static Site Generation）项目通常以静态文件为主，配合动态服务实现数据驱动。这种架构在团队协作中容易出现构建和部署的混乱，因为前端和后端的代码和配置需要严格对齐。在2024-2026年，SSG项目普遍采用Next.js、Nuxt.js、Astro等框架，它们都支持SSG或SSR模式。关键在于构建流程的自动化和环境配置的统一，尤其是构建输出路径、请求头配置、CDN策略、依赖管理这些细节容易成为团队协作的雷区。如果这些配置不一致，用户访问时可能遇到404、500错误，甚至资源加载失败。 二 具体操作方法或配置步骤 在Vercel上部署SSG项目，首先需要在`vercel.json`里配置`outputDirectory`参数，确保构建输出路径正确。例如： ```json { "outputDirectory": "dist" } ``` 然后在`gitignore`里设置`.env`文件，避免敏感信息泄露。部署时可以使用`vercel deploy --prod`命令直接推送到生产环境，但必须配合CI/CD流水线，防止误操作。如果团队使用GitHub，可以在`.github/workflows/deploy.yml`里添加构建任务，确保每次提交都自动触发部署。构建任务需要指定`buildCommand`和`routes`，例如： ```yaml buildCommand: "npm run build" routes: - src// - public// ``` 这样能保证静态资源和源代码都被正确部署。 三 常见踩坑场景与避坑方案 SSG项目最大的坑是静态资源路径错误，尤其是跨域问题和CDN缓存策略不一致。比如在使用`gatsby-plugin-image`时，如果没有配置`gatsby-config.js`里的`image`字段，会导致图片无法加载。另一个问题是构建输出路径不一致，导致Vercel无法正确识别静态文件。解决方案是统一使用`outputDirectory`指定输出路径，并在构建脚本里加上`--output-path dist`参数。此外，团队协作时容易出现环境变量不一致的问题，比如`NEXT_PUBLIC_API_URL`没同步到所有环境，导致前端无法连接后端。解决方法是使用Vercel的env变量管理，或者配合`dotenv`加载`.env`文件，确保所有成员使用相同的配置。 四 性能影响或效率对比 SSG项目的性能优势在于无需服务端渲染，静态文件直接由CDN分发，响应速度要比传统SSR或动态网站快30%-50%。但性能也取决于构建流程的优化，比如未压缩的图片或未预处理的CSS会导致加载变慢。我见过一个SSG项目因为没启用`next.config.js`里的`swc`配置，导致构建时间翻倍，从原来的10秒变成30秒。启用`swc`后，构建时间下降到8秒以内。另外，未配置`headers`和`redirects`会导致HTTP请求被缓存到错误位置，影响SEO和用户体验。相比之下，用`vercel.json`里的`headers`和`routes`配置，能确保每个请求都被正确处理，提升加载速度。 五 适用场景与局限性 SSG项目适合文档类、个人博客、营销页面等对性能要求高的场景，因为静态文件加载速度快，且无需服务端处理。不过，如果项目需要复杂交互或实时数据，SSG就不够用了。我见过一个电商平台用SSG，但因为需要用户登录和支付，导致不得不引入SSR或动态渲染，结果反而增加了构建复杂度。此外，SSG项目在团队协作时容易出现配置不一致的问题，比如`outputDirectory`没统一，导致不同成员构建的文件结构不同。这时候必须用CI/CD流水线强制校验构建输出，确保所有成员使用相同的配置。 六 替代方案或进阶技巧 如果SSG项目太重，可以考虑用`Astro`或`VuePress`来替代，它们构建更快，且支持更灵活的静态资源管理。我用过`Astro`的一个技巧是，把`public/`目录直接上传到CDN，而不是交给Vercel，这样能获得更稳定的服务。在团队协作中，我用过`Lerna`和`Nx`来管理多项目，确保各个模块的依赖和构建配置保持一致。另一个进阶技巧是用`Cloudflare Workers`做预渲染层，把SSG生成的页面提前缓存，减少服务器压力。不过要注意Workers的内存限制，超过256MB的脚本会触发错误。 七 依赖管理与版本控制 SSG项目依赖的框架和工具必须严格版本控制，尤其是`next.js`和`react`的版本差异容易导致兼容性问题。我用过`npm install --save-dev next react`时，没注意`react`版本和`next`版本是否匹配，结果构建失败。后来改用`package.json`里的`resolutions`字段，强制指定版本，确保所有依赖一致。例如： ```json { "resolutions": { "react": "18.2.0", "next": "13.4.0" } } ``` 此外，在多团队协作时，我用过`GitHub Actions`设置`npm install`和`npm build`的检查任务，确保每次提交都通过依赖校验，否则禁止合并到主分支。 八 静态资源优化与缓存策略 静态资源优化是SSG项目的关键，尤其是图片和字体文件。我用过`next/image`配合`next.config.js`里的`images`配置，确保图片使用WebP格式并进行懒加载。例如： ```js module.exports = { images: { domains: ['example.com'], unoptimized: true } } ``` 同时，我用过`Vercel`的`headers`配置，设置`Cache-Control`为`public, max-age=31536000, immutable`，确保图片和CSS文件被浏览器永久缓存。不过要注意，如果资源需要频繁更新，可以动态修改`Cache-Control`值，比如使用`no-cache`或`no-store`，避免旧资源残留。 九 构建流程自动化与CI/CD 构建流程自动化是SSG项目的核心，尤其是多环境部署。我用过`GitHub Actions`和`GitLab CI`来管理构建和部署任务，确保每次提交都触发自动化流程。例如，在`.github/workflows/deploy.yml`里设置： ```yaml - name: Build run: npm run build - name: Deploy run: vercel deploy --prod --force ``` 同时，我强制要求使用`pre-commit`和`pre-push`钩子，确保代码风格和格式正确。比如用`husky`配合`lint-staged`，在提交前自动格式化和校验代码： ```bash npx husky add .husky/pre-commit "npx lint-staged" ``` 这样能避免构建任务因为代码问题而失败。 十 环境变量管理与安全策略 环境变量管理是SSG项目最容易出错的地方，尤其是`NEXT_PUBLIC_`前缀变量和`.env`文件的使用。我用过`dotenv`加载`.env`，同时在CI/CD里设置`VERCEL_ENV`变量，确保不同环境使用不同配置。例如： ```bash VERCEL_ENV=production ``` 在`next.config.js`里，我用过`process.env`来读取变量，但后来发现有些变量在构建时无法访问，只能通过Vercel的env变量接口获取。为了安全，我强制要求所有敏感信息（如API密钥、数据库连接）通过`Vercel`内置的变量管理，而不是写在`.env`文件里。这样能避免泄露风险。 十一 动态服务与SSG的配合 SSG项目和动态服务（如Node.js API）的配合是关键，尤其是部署时的入口点设置。我用过`vercel.json`里的`functions`配置，确保API服务在正确目录下运行。例如： ```json { "functions": ["api//"] } ``` 同时，在`next.config.js`里配置`basePath`和`assetPrefix`，确保静态文件和API请求路径正确。例如： ```js module.exports = { basePath: '/my-app', assetPrefix: '/my-app' } ``` 这样能避免部署后路径错误，比如`/api`变成`/my-app/api`，导致请求失败。 十二 多环境部署与版本控制 多环境部署需要严格版本控制，尤其是`vercel.json`和`next.config.js`里的配置。我用过`vercel.json`的`environments`字段，区分开发、测试和生产环境。例如： ```json { "environments": { "production": { "outputDirectory": "dist" }, "staging": { "outputDirectory": "dist-staging" } } } ``` 在CI/CD里，我用过`--env`参数指定环境，比如`vercel deploy --prod --env production`。这样能避免误部署到生产环境，同时确保不同环境使用不同的配置。 十三 构建失败的调试技巧 构建失败的调试需要掌握多个工具，比如`next build`和`next export`的输出日志，`swc`的编译日志，以及`webpack`的错误提示。我用过`next build --verbose`来获取详细日志，发现某个`@emotion`库的版本冲突导致构建失败。解决方法是用`npm install`时添加`--save-exact`，确保依赖版本一致。另外，我用过`npm ls`检查依赖树，发现某个库有多条路径，导致构建出错。这时候需要手动删除或更新依赖。 十四 团队协作中的构建配置冲突 团队协作时，构建配置冲突是常见问题。我用过`husky`和`lint-staged`强制提交前格式化和校验代码，避免构建因为格式问题而失败。例如： ```bash npm install --save-dev husky lint-staged prettier npx husky install npx husky add .husky/pre-commit "npx lint-staged" ``` 同时，我用过`conventional-commits`规范提交信息，确保每个提交都有明确的目的，比如`feat: add new page`或`fix: resolve build error`。这样能减少构建任务因为误操作而失败。 十五 热更新与部署策略 热更新是SSG项目的重要特性，但需要合理配置。我用过`next.config.js`里的`revalidate`参数，设置`revalidate: 60 60 24`，确保每次部署后页面缓存更新周期为24小时。不过，在团队协作时，我发现有些成员没设置`revalidate`，导致旧页面长期缓存。解决方法是用`vercel.json`里的`revalidate`字段统一配置。另外，我用过`vercel deploy --prod --force`来强制部署新版本，确保旧版本被下线。这样能避免用户访问到错误的页面。