Débogage du déploiement sur Railway et Vercel
/SKILLDépannage des problèmes de déploiement sur les plateformes Railway et Vercel.
Deployment Debugging: Railway & Vercel
Debugging deployment issues on Railway and Vercel platforms.
When to Use
- Build failures on Railway or Vercel
- Environment variable issues
- Cold start problems
- Runtime errors in production
- Deployment configuration issues
Railway Debugging
Build Failures
#### Symptom: Build hangs or times out
Check:
# Railway build logs
railway logs --build
# Common causes:
# 1. No Dockerfile or nixpacks.toml
# 2. Large dependencies being installed
# 3. Memory limits exceeded
Solution - Add `railway.toml`:
[build]
builder = "nixpacks"
buildCommand = "cargo build --release"
[deploy]
startCommand = "cargo run --release"
healthcheckPath = "/health"
healthcheckTimeout = 300
#### Symptom: Cargo/Rust build fails
Common issues:
# Missing system dependencies
# Add to nixpacks.toml:
[phases.setup]
aptPkgs = ["libssl-dev", "pkg-config"]
# Or use Dockerfile
FROM rust:1.75 as builder
RUN apt-get update && apt-get install -y libssl-dev pkg-config
#### Symptom: Node.js build fails
# Check Node version
# Add to package.json:
{
"engines": {
"node": ">=20"
}
}
# Or railway.toml:
[build]
nixpacksConfigPath = "nixpacks.toml"
Environment Variables
#### Symptom: Env vars not available at build time
Solution: Use Railway's variable references:
# In Railway dashboard, use references:
DATABASE_URL=${{Postgres.DATABASE_URL}}
# Or for secrets:
API_KEY=${{secrets.API_KEY}}
#### Symptom: Env vars not in runtime
Check:
// Debug endpoint
#[get("/debug/env")]
fn debug_env() -> String {
std::env::vars()
.filter(|(k, _)| !k.contains("SECRET") && !k.contains("KEY"))
.map(|(k, v)| format!("{}: {}", k, v))
.collect::<Vec<_>>()
.join("\n")
}
Networking
#### Symptom: Can't connect to database
Check Railway's internal networking:
# Use internal hostname for Railway services
DATABASE_URL=postgres://user:pass@postgres.railway.internal:5432/db
# Not the public URL for internal services
#### Symptom: Port issues
# Railway sets PORT automatically
# Use it in your code:
let port = std::env::var("PORT").unwrap_or("3000".to_string());
Health Checks
# railway.toml
[deploy]
healthcheckPath = "/health"
healthcheckTimeout = 300
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 3
// Implement health endpoint
#[get("/health")]
fn health() -> &'static str {
"OK"
}
Vercel Debugging
Build Failures
#### Symptom: Next.js build fails
# Check Vercel build logs
vercel logs <deployment-url>
# Common fixes in next.config.js:
module.exports = {
eslint: {
ignoreDuringBuilds: true, // If ESLint issues blocking
},
typescript: {
ignoreBuildErrors: true, // Last resort for TS errors
},
};
#### Symptom: "Module not found" in build
# Ensure dependencies in dependencies, not devDependencies
# Or configure for build:
{
"vercel": {
"installCommand": "bun install --production=false"
}
}
Environment Variables
#### Symptom: Env vars undefined in client
Root cause: Only `NEXTPUBLIC*` vars are exposed to client.
// Server-side only
const apiKey = process.env.API_KEY; // Works in server components/API routes
// Client-side
const publicKey = process.env.NEXT_PUBLIC_KEY; // Must have NEXT_PUBLIC_ prefix
#### Symptom: Env vars not in serverless functions
Check Vercel dashboard Environment Variables:
- Production vs Preview vs Development
- Scope to specific branches if needed
Serverless Function Issues
#### Symptom: Function timeout
// vercel.json - increase timeout (Pro/Enterprise only)
{
"functions": {
"app/api/**/*.ts": {
"maxDuration": 60
}
}
}
// For Hobby plan, optimize function:
export const maxDuration = 10; // seconds
#### Symptom: Cold starts slow
Solutions:
- Use Edge Runtime for simple functions:
export const runtime = 'edge';
- Keep functions warm (Pro feature):
{
"crons": [{
"path": "/api/health",
"schedule": "*/5 * * * *"
}]
}
- Reduce bundle size:
// Only import what you need
import { specificFunction } from 'large-library/specific';
#### Symptom: 500 errors in production only
Debug locally with production env:
vercel env pull .env.local
vercel dev
Check function logs:
vercel logs <deployment-url> --follow
Edge Functions
#### Symptom: API not available in Edge
Root cause: Node.js APIs not available in Edge Runtime.
// Bad - uses Node.js
import { readFile } from 'fs';
// Good - Edge compatible
ex
