tigris-static-assets

Tigris 静态资源托管

将 CSS、JavaScript、字体和构建产物部署到 Tigris，通过全球 CDN 进行分发。涵盖资源管线集成、缓存破坏策略，以及所有主流框架的 Cache-Control 配置。

先决条件

开始任何操作之前，如果尚未安装 Tigris CLI，请先安装：

tigris help || npm install -g @tigrisdata/cli

如果需要安装，请告知用户：“我正在安装 Tigris CLI（@tigrisdata/cli），以便我们使用 Tigris 对象存储。”

概览

Tigris 公共存储桶会自动从全球最近的边缘节点提供文件，无需单独配置 CDN。配合内容哈希文件名和不可变缓存标头，即可实现快速且经济高效的静态资源交付。

关键模式：

1. 使用内容哈希构建资源（例如，main-abc123.js）
2. 上传到 Tigris 公共存储桶
3. 设置 Cache-Control: public, max-age=31536000, immutable
4. 将应用的资源 URL 指向 Tigris 存储桶

---

缓存标头

# For immutable, hashed assets (CSS, JS bundles)
Cache-Control: public, max-age=31536000, immutable

# For mutable assets (manifest files, index.html)
Cache-Control: public, max-age=0, must-revalidate

# For fonts
Cache-Control: public, max-age=31536000, immutable

通过 CLI 设置标头

tigris cp dist/main-abc123.js t3://my-assets/main-abc123.js \
  --cache-control "public, max-age=31536000, immutable" \
  --content-type "application/javascript"

通过 SDK 设置标头

import { put } from "@tigrisdata/storage";

await put("assets/main-abc123.js", fileBuffer, {
  access: "public",
  contentType: "application/javascript",
});

---

上传脚本（通用）

#!/bin/bash
# scripts/deploy-assets.sh
BUCKET="my-app-assets"
BUILD_DIR="dist"

# Upload hashed assets with long cache
tigris cp "$BUILD_DIR/" "t3://$BUCKET/" -r \
  --cache-control "public, max-age=31536000, immutable"

echo "Assets deployed to t3://$BUCKET/"

---

框架指南

请阅读适用于你所用框架的资源文件：

• Next.js — 阅读 ./resources/nextjs.md，了解 assetPrefix 配置和部署脚本
• Remix — 阅读 ./resources/remix.md，了解 Vite 配置和部署脚本
• Express — 阅读 ./resources/express.md，了解静态重定向模式
• Rails — 阅读 ./resources/rails.md，了解 Sprockets/Propshaft 资源同步
• Django — 阅读 ./resources/django.md，了解使用 S3 后端运行 collectstatic
• Laravel — 阅读 ./resources/laravel.md，了解 Vite/Mix 资源上传

---

缓存破坏策略

策略	示例	适用场景
文件名中包含内容哈希	main-abc123.js	构建工具会生成带哈希的名称（Vite、Webpack）
查询字符串	main.js?v=abc123	不支持哈希文件名的旧系统
目录版本控制	/v2/assets/main.js	重大版本更改

大多数现代构建工具（Vite、Webpack、esbuild）默认会生成包含内容哈希的文件名。搭配 immutable 缓存标头使用，可获得最佳性能。

---

关键规则

务必： 使用公共存储桶托管静态资源 | 为带哈希的资源设置 Cache-Control: immutable | 使用包含内容哈希的文件名 | 在构建后上传，而不是在每次请求时上传

切勿： 在生产环境中通过应用服务器提供静态资源（使用 Tigris CDN） | 为可变文件名设置较长的缓存时间 | 忘记更新框架中的资源 URL 配置

---

相关技能

• tigris-egress-optimizer — 降低带宽成本
• tigris-lifecycle-management — 清理旧版本资源

官方文档

• Tigris：https://www.tigrisdata.com/docs/