Next.js + Shopify OAuth 第三方应用接入完整指南

Next.js + Shopify OAuth 第三方应用接入完整指南

本文将详细介绍如何使用 Next.js 14 (App Router) 创建一个非嵌入式 Shopify 应用，实现从 OAuth 认证到获取商品列表的完整流程。

🎯 项目概述

• 技术栈: Next.js 14 + TypeScript + Tailwind CSS
• 架构: 非嵌入式应用 + 无服务器函数
• 认证: OAuth 2.0 流程
• 存储: 本地文件系统会话存储

📋 前置准备

1. Shopify Partner 账户设置

# 1. 访问 Shopify Partner Dashboard  
https://partners.shopify.com/  
  
# 2. 创建新应用  
- 应用类型: Public app  
- 应用名称: 自定义  
- 应用URL: https://your-domain.com  
- 重定向URL: https://your-domain.com/api/auth/callback  

2. 开发环境准备

# 创建 Next.js 项目  
npx create-next-app@latest shopify-app --typescript --tailwind --app  
  
# 安装 Shopify 依赖  
npm install @shopify/shopify-api  

🔧 核心实现

1. 环境变量配置

# .env.local  
SHOPIFY_API_KEY=your_api_key  #从你的shopify app 设置界面获取
SHOPIFY_API_SECRET=your_api_secret  #从你的shopify app 设置界面设置
SHOPIFY_SCOPES=read_products,read_orders  
SHOPIFY_HOST=https://your-domain.com # 我们应用的域名 

2. Shopify 配置初始化

// src/lib/shopify.ts  
import { shopifyApi, LATEST_API_VERSION } from '@shopify/shopify-api';  
  
export const shopify = shopifyApi({  
    apiKey: process.env.SHOPIFY_API_KEY!,  
    apiSecretKey: process.env.SHOPIFY_API_SECRET!,  
    scopes: process.env.SHOPIFY_SCOPES!.split(','),  
    hostName: process.env.SHOPIFY_HOST!.replace(/https?:\/\//, ''),  
    apiVersion: LATEST_API_VERSION,  
    isEmbeddedApp: false, // 非嵌入式应用  
});  

3. 会话存储简易实现

shopify 是标准的 OAuth2.0 授权模型，获取的 access_token 这里简单存到文件里，用来实现后边请求商品列表等资源接口，实际也可用用数据库或者redis做持久化存储和缓存管理

// src/lib/session-storage.ts  
import fs from 'fs';  
import path from 'path';  
  
const SESSIONS_DIR = path.join(process.cwd(), '.sessions');  
  
interface SessionData {  
    id: string;  
    shop: string;  
    accessToken: string;  
    expires?: Date;  
}  
  
export class FileSessionStorage {  
static async storeSession(session: SessionData): Promise<boolean> {  
    try {  
        if (!fs.existsSync(SESSIONS_DIR)) {  
    fs.mkdirSync(SESSIONS_DIR, { recursive: true });  
}  
  
const filePath = path.join(SESSIONS_DIR, `${session.id}.json`);  
    fs.writeFileSync(filePath, JSON.stringify(session, null, 2));  
    return true;  
    } catch (error) {  
    console.error('存储会话失败:', error);  
    return false;  
    }  
}  
  
static async loadSession(id: string): Promise<SessionData | undefined> {  
try {  
    const filePath = path.join(SESSIONS_DIR, `${id}.json`);  
    if (!fs.existsSync(filePath)) return undefined;  
  
    const data = fs.readFileSync(filePath, 'utf-8');  
    return JSON.parse(data);  
    } catch (error) {  
        console.error('加载会话失败:', error);  
        return undefined;  
    }  
}  
}  

4. OAuth 认证流程

认证入口 API

商家提供店铺名称，调用该接口触发认证流程

// src/app/api/auth/route.ts  
import { NextRequest, NextResponse } from 'next/server';  
  
export async function GET(request: NextRequest) {  
const { searchParams } = new URL(request.url);  
const shop = searchParams.get('shop');  
  
if (!shop) {  
return NextResponse.json({ error: '缺少shop参数' }, { status: 400 });  
}  
  
// 构建 OAuth 授权 URL  
const scopes = process.env.SHOPIFY_SCOPES!;  
const redirectUri = `${process.env.SHOPIFY_HOST}/api/auth/callback`;  
const state = Math.random().toString(36).substring(7);  
  
const authUrl = `https://${shop}/admin/oauth/authorize?` +  
`client_id=${process.env.SHOPIFY_API_KEY}&` +  
`scope=${scopes}&` +  
`redirect_uri=${redirectUri}&` +  
`state=${state}`;  

// 重定向到商家店铺的授权页面，商家点击安装，完成授权
return NextResponse.redirect(authUrl); 
}  

OAuth 回调处理

授权完成获取code，服务端拿code获取 access_token, access_token 可以用来访问 shopify 数据

// src/app/api/auth/callback/route.ts  
import { NextRequest, NextResponse } from 'next/server';  
import { FileSessionStorage } from '@/lib/session-storage';  
  
export async function GET(request: NextRequest) {  
const { searchParams } = new URL(request.url);  
const code = searchParams.get('code');  
const shop = searchParams.get('shop');  
  
if (!code || !shop) {  
return NextResponse.redirect('/error?message=授权失败');  
}  
  
try {  
// 交换访问令牌  
const tokenResponse = await fetch(`https://${shop}/admin/oauth/access_token`, {  
method: 'POST',  
headers: { 'Content-Type': 'application/json' },  
body: JSON.stringify({  
client_id: process.env.SHOPIFY_API_KEY,  
client_secret: process.env.SHOPIFY_API_SECRET,  
code,  
}),  
});  
  
const { access_token } = await tokenResponse.json();  
  
// 存储会话  
const sessionId = `${shop}_session`;  // sessionId是会话token，用来保持登录态
await FileSessionStorage.storeSession({  
id: sessionId,  
shop,  
accessToken: access_token,  
});  
  
// 重定向到商品页面  
const response = NextResponse.redirect(`${process.env.SHOPIFY_HOST}/products`);  
response.cookies.set('shopify_session', sessionId, {  
httpOnly: true,  
secure: true,  
sameSite: 'lax',  
maxAge: 60 * 60 * 24 * 7, // 7天  
});  
  
return response;  
} catch (error) {  
console.error('OAuth回调错误:', error);  
return NextResponse.redirect('/error?message=授权处理失败');  
}  
}  

5. 商品数据获取

Shopify 使用 GraphQL 语法请求接口

// src/app/api/products/route.ts  
import { NextRequest, NextResponse } from 'next/server';  
import { FileSessionStorage } from '@/lib/session-storage';  
  
const PRODUCTS_QUERY = `  
query getProducts($first: Int!) {  
    products(first: $first) {  
        edges {  
            node {  
                id  
                title  
                handle  
                status  
                createdAt  
                updatedAt  
                priceRangeV2 {  
                    minVariantPrice {  
                    amount  
                    currencyCode  
                   }  
                }  
                featuredImage {  
                    url  
                    altText  
                }  
            }  
        }  
     }  
}  
`;  
  
export async function GET(request: NextRequest) {  
try {  
const sessionId = request.cookies.get('shopify_session')?.value;  
if (!sessionId) {  
return NextResponse.json({ error: '未找到会话' }, { status: 401 });  
}  
  
const session = await FileSessionStorage.loadSession(sessionId);  
if (!session) {  
return NextResponse.json({ error: '会话已过期' }, { status: 401 });  
}  
  
// 调用 Shopify GraphQL API  
const response = await fetch(`https://${session.shop}/admin/api/2024-01/graphql.json`, {  
method: 'POST',  
headers: {  
'Content-Type': 'application/json',  
'X-Shopify-Access-Token': session.accessToken,  
},  
body: JSON.stringify({  
query: PRODUCTS_QUERY,  
variables: { first: 50 },  
}),  
});  
  
const data = await response.json();  
  
if (data.errors) {  
throw new Error(`GraphQL错误: ${JSON.stringify(data.errors)}`);  
}  
  
return NextResponse.json({  
success: true,  
products: data.data.products.edges.map((edge: any) => edge.node),  
shop: session.shop,  
});  
  
} catch (error) {  
console.error('获取商品失败:', error);  
return NextResponse.json(  
{ error: '获取商品失败', details: error.message },  
{ status: 500 }  
);  
}  
}  

6. 前端页面实现

店铺连接页面

// src/app/shopify/page.tsx  
'use client';  
  
import { useState } from 'react';  
  
export default function ShopifyPage() {  
const [shopUrl, setShopUrl] = useState('');  
const [isConnecting, setIsConnecting] = useState(false);  
  
const handleConnect = async () => {  
if (!shopUrl.trim()) return;  
  
setIsConnecting(true);  
  
// 标准化店铺URL  
let shop = shopUrl.trim();  
if (!shop.includes('.myshopify.com')) {  
shop = `${shop}.myshopify.com`;  
}  
  
// 跳转到OAuth认证  
window.location.href = `/api/auth?shop=${encodeURIComponent(shop)}`;  
};  
  
return (  
<div className="min-h-screen bg-gradient-to-br from-blue-50 to-purple-50 flex items-center justify-center p-4">  
<div className="bg-white rounded-2xl shadow-xl p-8 w-full max-w-md">  
<h1 className="text-2xl font-bold text-gray-900 mb-6 text-center">  
连接 Shopify 店铺  
</h1>  
  
<div className="space-y-4">  
<div>  
<label className="block text-sm font-medium text-gray-700 mb-2">  
店铺地址  
</label>  
<input  
type="text"  
value={shopUrl}  
onChange={(e) => setShopUrl(e.target.value)}  
placeholder="mystore 或 mystore.myshopify.com"  
className="w-full px-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent"  
disabled={isConnecting}  
/>  
</div>  
  
<button  
onClick={handleConnect}  
disabled={!shopUrl.trim() || isConnecting}  
className="w-full bg-blue-600 text-white py-3 px-4 rounded-lg hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"  
>  
{isConnecting ? '连接中...' : '连接店铺'}  
</button>  
</div>  
</div>  
</div>  
);  
}  

商品列表页面

// src/app/products/page.tsx  
'use client';  
  
import { useState, useEffect } from 'react';  
import Image from 'next/image';  
  
interface Product {  
id: string;  
title: string;  
status: string;  
priceRangeV2: {  
minVariantPrice: {  
amount: string;  
currencyCode: string;  
};  
};  
featuredImage?: {  
url: string;  
altText?: string;  
};  
}  
  
export default function ProductsPage() {  
const [products, setProducts] = useState<Product[]>([]);  
const [loading, setLoading] = useState(true);  
const [shop, setShop] = useState('');  
  
const fetchProducts = async () => {  
try {  
setLoading(true);  
const response = await fetch('/api/products');  
const data = await response.json();  
  
if (data.success) {  
setProducts(data.products);  
setShop(data.shop);  
} else {  
console.error('获取商品失败:', data.error);  
}  
} catch (error) {  
console.error('请求失败:', error);  
} finally {  
setLoading(false);  
}  
};  
  
useEffect(() => {  
fetchProducts();  
}, []);  
  
if (loading) {  
return (  
<div className="min-h-screen flex items-center justify-center">  
<div className="text-center">  
<div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600 mx-auto mb-4"></div>  
<p className="text-gray-600">加载商品中...</p>  
</div>  
</div>  
);  
}  
  
return (  
<div className="min-h-screen bg-gray-50 py-8">  
<div className="max-w-7xl mx-auto px-4">  
<div className="flex justify-between items-center mb-8">  
<div>  
<h1 className="text-3xl font-bold text-gray-900">商品列表</h1>  
<p className="text-gray-600 mt-2">店铺: {shop}</p>  
</div>  
<button  
onClick={fetchProducts}  
className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700 transition-colors"  
>  
刷新  
</button>  
</div>  
  
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-6">  
{products.map((product) => (  
<div key={product.id} className="bg-white rounded-lg shadow-md overflow-hidden">  
{product.featuredImage && (  
<div className="aspect-square relative">  
<Image  
src={product.featuredImage.url}  
alt={product.featuredImage.altText || product.title}  
fill  
className="object-cover"  
/>  
</div>  
)}  
  
<div className="p-4">  
<h3 className="font-semibold text-gray-900 mb-2 line-clamp-2">  
{product.title}  
</h3>  
  
<div className="flex justify-between items-center">  
<span className="text-lg font-bold text-green-600">  
{product.priceRangeV2.minVariantPrice.currencyCode} {product.priceRangeV2.minVariantPrice.amount}  
</span>  
  
<span className={`px-2 py-1 rounded-full text-xs font-medium ${  
product.status === 'ACTIVE'  
? 'bg-green-100 text-green-800'  
: 'bg-gray-100 text-gray-800'  
}`}>  
{product.status}  
</span>  
</div>  
</div>  
</div>  
))}  
</div>  
  
{products.length === 0 && (  
<div className="text-center py-12">  
<p className="text-gray-500 text-lg">暂无商品</p>  
</div>  
)}  
</div>  
</div>  
);  
}