跳到主要内容

Express.js 集成指南

📦 安装​

npm install @anima/express

🚀 使用方法​

基础集成​

const express = require('express');
const anima = require('@anima/express');

const app = express();

// 开发环境自动启用隧道
if (process.env.NODE_ENV === 'development') {
  app.use(anima({
    token: process.env.ANIMA_TOKEN,
    subdomain: 'myapp',  // 可选：自定义子域名
    autoStart: true,
    onReady: (url) => {
      console.log(`🌐 公网地址: ${url}`);
    }
  }));
}

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server started on http://localhost:3000');
});

运行​

ANIMA_TOKEN=your-token npm start

# 输出：
# Server started on http://localhost:3000
# 🌐 公网地址: https://myapp.anima4.cn

⚙️ 配置选项​

app.use(anima({
  // 必需配置
  token: process.env.ANIMA_TOKEN,
  
  // 隧道配置
  subdomain: 'myapp',
  region: 'cn-shanghai',
  
  // 功能开关
  enabled: process.env.NODE_ENV === 'development',
  autoStart: true,
  openBrowser: true,
  copyToClipboard: true,
  
  // 安全配置
  allowedIPs: ['192.168.1.0/24'],
  password: 'secret',
  
  // 回调函数
  onReady: (url) => {
    console.log(`🚀 隧道就绪: ${url}`);
  },
  onError: (error) => {
    console.error(`❌ 隧道错误: ${error}`);
  },
  onClose: () => {
    console.log('🔒 隧道已关闭');
  }
}));

🔧 高级用法​

条件启用​

// 只在特定条件下启用
const shouldEnableAnima = process.env.NODE_ENV === 'development' && 
                         process.env.ENABLE_TUNNEL === 'true';

if (shouldEnableAnima) {
  app.use(anima({
    token: process.env.ANIMA_TOKEN,
    subdomain: process.env.ANIMA_SUBDOMAIN || 'myapp'
  }));
}

自定义中间件​

// 自定义中间件，在 Anima 之前执行
app.use((req, res, next) => {
  console.log(`📝 请求: ${req.method} ${req.path}`);
  next();
});

// Anima 隧道中间件
app.use(anima({
  token: process.env.ANIMA_TOKEN,
  requestLogger: true  // 启用请求日志
}));

📝 示例项目​

完整的 Express 应用​

// app.js
const express = require('express');
const anima = require('@anima/express');
const cors = require('cors');

const app = express();

// 中间件
app.use(cors());
app.use(express.json());

// Anima 隧道（开发环境）
if (process.env.NODE_ENV === 'development') {
  app.use(anima({
    token: process.env.ANIMA_TOKEN,
    subdomain: 'my-express-api',
    onReady: (url) => {
      console.log(`🌐 API 已暴露: ${url}`);
    }
  }));
}

// 路由
app.get('/api/users', (req, res) => {
  res.json([
    { id: 1, name: 'John Doe' },
    { id: 2, name: 'Jane Smith' }
  ]);
});

app.post('/api/users', (req, res) => {
  const { name } = req.body;
  res.json({ id: Date.now(), name });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`🚀 服务器运行在端口 ${PORT}`);
});

环境配置​

# .env
NODE_ENV=development
ANIMA_TOKEN=anima_xxxxxxxxxxxx
ANIMA_SUBDOMAIN=my-express-api

🔒 安全注意事项​

1. 环境隔离​

// ✅ 推荐：只在开发环境启用
if (process.env.NODE_ENV === 'development') {
  app.use(anima({ /* ... */ }));
}

// ❌ 危险：不要在生产环境启用
app.use(anima({ /* ... */ }));

2. Token 安全​

# ✅ 使用环境变量
ANIMA_TOKEN=your-token

# ✅ 使用 .env 文件（并加入 .gitignore）
echo "ANIMA_TOKEN=your-token" >> .env
echo ".env" >> .gitignore

# ❌ 不要硬编码在代码中
token: 'hardcoded-token-123'  // 危险！

3. 访问控制​

app.use(anima({
  token: process.env.ANIMA_TOKEN,
  
  // IP 白名单
  allowedIPs: [
    '192.168.1.0/24',  // 公司内网
    '10.0.0.0/8',      // VPN 网段
  ],
  
  // 访问密码
  password: process.env.ANIMA_PASSWORD,
  
  // 限制连接数
  maxConnections: 5,
}));

🆘 故障排查​

常见问题​

1. 隧道无法启动​

# 检查 Token 是否正确
echo $ANIMA_TOKEN

# 检查网络连接
curl https://api.anima4.cn/health

# 查看详细日志
DEBUG=anima:* npm start

2. 子域名已被占用​

// 使用随机子域名
app.use(anima({
  subdomain: null,  // 自动生成随机子域名
}));

// 或添加后缀
app.use(anima({
  subdomain: 'myapp-' + Date.now(),
}));

3. 连接频繁断开​

app.use(anima({
  token: process.env.ANIMA_TOKEN,
  reconnect: true,        // 启用自动重连
  reconnectInterval: 5000, // 重连间隔（毫秒）
  maxReconnects: 10,      // 最大重连次数
}));

🔗 相关链接​