# Required Environment Variables for Deploying wechat-article-exporter: NITRO_KV_DRIVER and NITRO_KV_BASE Explained

> Deploy wechat-article-exporter easily by understanding NITRO_KV_DRIVER and NITRO_KV_BASE environment variables. Learn how to configure your storage backend and path for successful deployment.

- Repository: [公众号文章工具箱/wechat-article-exporter](https://github.com/wechat-article/wechat-article-exporter)
- Tags: how-to-guide
- Published: 2026-05-26

---

**Deploying wechat-article-exporter requires setting `NITRO_KV_DRIVER` to select the storage backend (fs, memory, or cloudflare-kv-binding) and `NITRO_KV_BASE` to define the storage path or namespace.**

The **wechat-article-exporter** is a Nuxt 3-based application that proxies WeChat API requests and caches article data using Nitro's storage layer. Understanding the required environment variables for deploying wechat-article-exporter ensures proper data persistence across local Docker deployments, Cloudflare Workers, and development environments.

## Understanding Nitro KV Storage in wechat-article-exporter

The application uses **Nitro's built-in storage system** to cache article metadata, HTML content, and download queues. In [`nuxt.config.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/nuxt.config.ts), the storage configuration references the `NITRO_KV_DRIVER` and `NITRO_KV_BASE` environment variables to initialize the appropriate backend. Without these variables, the server cannot persist cache data between restarts or manage concurrent download operations effectively.

## Required Environment Variables

Two variables are mandatory for any deployment of wechat-article-exporter.

### NITRO_KV_DRIVER

This variable selects the **storage driver** for the Nitro KV layer. Valid options include:

- **`fs`** – File-system-based storage for local deployments and Docker containers
- **`memory`** – In-memory storage that resets on server restart (useful for development)
- **`cloudflare-kv-binding`** – Cloudflare KV namespace for edge deployments

According to the source code in [`nuxt.config.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/nuxt.config.ts), the driver configuration falls back to `memory` if not specified, but production deployments must explicitly set this to avoid data loss.

### NITRO_KV_BASE

This variable defines the **base path or namespace** for the selected driver:

- For `fs` driver: A directory path relative to the project root (e.g., `.data/kv`)
- For `cloudflare-kv-binding` driver: The KV namespace binding name
- For `memory` driver: A namespace identifier (optional, but recommended for multi-instance deployments)

## Configuration Implementation in nuxt.config.ts

The configuration file implements these variables under the `nitro.storage.kv` key:

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    storage: {
      kv: {
        driver: process.env.NITRO_KV_DRIVER || 'memory',
        base: process.env.NITRO_KV_BASE,
        // Additional driver-specific options
      }
    }
  }
})

```

The server utilities in [`server/utils/proxy-request.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/server/utils/proxy-request.ts) and the download orchestrator in [`utils/download/Downloader.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/utils/download/Downloader.ts) rely on this KV storage to cache WeChat API responses and manage download state across concurrent requests.

## Deployment Scenarios

### Local and Docker Deployment

For self-hosted Docker deployments, use the file system driver with a persistent volume:

```bash

# .env file or docker-compose environment

NITRO_KV_DRIVER=fs
NITRO_KV_BASE=.data/kv

```

The `Dockerfile` copies the repository and runs `yarn build`, but you must mount a volume to `./data/kv` to persist cache data between container restarts.

### Cloudflare Workers Deployment

When deploying to Cloudflare, switch to the edge-compatible driver:

```bash
NITRO_KV_DRIVER=cloudflare-kv-binding
NITRO_KV_BASE=WECHAT_CACHE

```

Ensure your [`wrangler.toml`](https://github.com/wechat-article/wechat-article-exporter/blob/main/wrangler.toml) or Cloudflare dashboard defines the `WECHAT_CACHE` binding pointing to a KV namespace.

### Development and Testing

For local development without persistence requirements:

```bash
NITRO_KV_DRIVER=memory
NITRO_KV_BASE=dev-cache

```

This configuration stores all data in RAM, meaning cached articles and download progress disappear when the dev server restarts.

## Optional Environment Variables

While `NITRO_KV_DRIVER` and `NITRO_KV_BASE` are mandatory, the application supports additional optional variables defined in `.env.example`:

- **`NUXT_AGGRID_LICENSE`** – Enterprise license key for AG-Grid features in the UI
- **`NUXT_DEBUG_MP_REQUEST`** – Enables verbose request logging for WeChat API debugging
- **`DEBUG_KEY`** – Secret token for accessing debug endpoints

## Summary

- **`NITRO_KV_DRIVER`** and **`NITRO_KV_BASE`** are required environment variables for deploying wechat-article-exporter in any environment.
- Set `NITRO_KV_DRIVER` to `fs` for Docker, `cloudflare-kv-binding` for Cloudflare, or `memory` for development.
- Configure `NITRO_KV_BASE` as a directory path for file-system storage or a namespace name for Cloudflare KV.
- The storage configuration resides in [`nuxt.config.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/nuxt.config.ts) and affects caching behavior in [`server/utils/proxy-request.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/server/utils/proxy-request.ts) and [`utils/download/Downloader.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/utils/download/Downloader.ts).
- Optional variables like `NUXT_AGGRID_LICENSE` enhance functionality but do not block deployment.

## Frequently Asked Questions

### What happens if I don't set NITRO_KV_DRIVER and NITRO_KV_BASE?

The application may fail to start or default to in-memory storage, causing all cached article data and download progress to be lost when the server restarts. The [`nuxt.config.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/nuxt.config.ts) file expects these variables to properly initialize the Nitro storage layer.

### Can I switch storage drivers without rebuilding the application?

Yes. Since the driver selection happens at runtime through environment variables, you can change `NITRO_KV_DRIVER` and `NITRO_KV_BASE` and restart the server without rebuilding. However, existing cached data in one storage backend (e.g., filesystem) will not automatically migrate to another (e.g., Cloudflare KV).

### Does wechat-article-exporter support Redis or other KV backends?

According to the current source code in [`nuxt.config.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/nuxt.config.ts), the application specifically configures the Nitro storage layer for `fs`, `memory`, and Cloudflare KV bindings. While Nitro supports additional drivers like Redis, you would need to modify the storage configuration object in [`nuxt.config.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/nuxt.config.ts) to implement unsupported drivers.

### How do I verify that my KV storage is working correctly?

Check the directory specified in `NITRO_KV_BASE` (for `fs` driver) to confirm that JSON cache files are being created. Alternatively, enable debug logging by setting `NUXT_DEBUG_MP_REQUEST=true` to observe storage read/write operations in the server logs. The [`Downloader.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/Downloader.ts) utility logs cache hits and misses during article fetching operations.