URL Relativa ao Servidor Deve Começar com a URL Relativa ao Servidor do SPWeb: Causa e Correção

Ao personalizar páginas do SharePoint, adicionar web parts ou trabalhar com soluções do SharePoint Framework, você pode ver o erro: “Server relative URL must start with SPWeb server relative URL.” Esse erro impede que uma página ou web part carregue corretamente. A causa raiz é uma incompatibilidade entre a URL fornecida no código ou configuração e o caminho relativo ao servidor real do site do SharePoint. Este artigo explica exatamente por que esse erro ocorre e como corrigi-lo usando o formato de URL correto.

Por que o Erro de URL Relativa ao Servidor Ocorre

O SharePoint usa URLs relativas ao servidor para referenciar recursos como páginas, listas e arquivos dentro de um conjunto de sites. Uma URL relativa ao servidor omite o protocolo e o domínio, começando com o caminho gerenciado, por exemplo /sites/MeuSite ou /equipes/MeuSiteEquipe. O erro “Server relative URL must start with SPWeb server relative URL” é acionado quando a URL fornecida não começa com o mesmo caminho do objeto web do SharePoint (SPWeb) atual.

O objeto SPWeb representa um site específico do SharePoint, que pode ser o site raiz de um conjunto de sites ou um sub-site. Cada SPWeb tem uma propriedade ServerRelativeUrl. Por exemplo, um site em https://contoso.sharepoint.com/sites/Projetos/Subsite tem uma URL relativa ao servidor de /sites/Projetos/Subsite. Se você tentar definir uma URL de página como /sites/Projetos/Paginas/Home.aspx, a URL é válida para a raiz do conjunto de sites, mas não para o sub-site. A URL correta para o sub-site seria /sites/Projetos/Subsite/Paginas/Home.aspx.

Cenários Comuns que Disparam o Erro

O erro aparece em várias situações:

• Web parts do SharePoint Framework (SPFx): Quando você codifica uma URL relativa ao servidor em uma propriedade de web part em vez de usar o contexto da página.
• Layouts de página ou master pages personalizados: Quando um link ou referência de recurso usa uma URL que não começa com o caminho relativo ao servidor do site atual.
• Scripts PowerShell ou código CSOM: Quando você passa uma URL relativa ao servidor para um método que espera que a URL seja relativa ao SPWeb atual.
• Fluxos de trabalho do SharePoint Designer: Quando uma ação de fluxo de trabalho referencia uma lista ou biblioteca usando uma URL absoluta ou relativa malformada.

O problema central é sempre o mesmo: a URL fornecida não começa com o mesmo caminho do site em que você está trabalhando.

Passos para Corrigir o Erro de URL Relativa ao Servidor

Método 1: Corrigir a URL em Web Parts do SharePoint Framework

1. Identifique a URL relativa ao servidor do web atual
   No código da sua web part SPFx, use this.context.pageContext.web.serverRelativeUrl para obter o caminho base correto. Para um site em /sites/MeuSite, essa propriedade retorna /sites/MeuSite.
2. Preceda o caminho base à sua URL de destino
   Em vez de escrever /sites/MeuSite/Listas/Tarefas, construa a URL dinamicamente: this.context.pageContext.web.serverRelativeUrl + '/Listas/Tarefas'. Isso garante que a URL final comece com o caminho SPWeb correto.
3. Teste a web part em um site diferente
   Implante a web part em um sub-site. Verifique se a URL é atualizada automaticamente para incluir o caminho do sub-site. Se a web part ainda usar uma URL codificada, o erro reaparecerá.

Método 2: Corrigir URLs em Código CSOM ou PowerShell

1. Obtenha o objeto SPWeb
   No CSOM, use clientContext.Web para obter o web atual. No PowerShell, use Get-SPWeb com a URL do site.
2. Leia a propriedade ServerRelativeUrl
   Para o objeto web, acesse $web.ServerRelativeUrl (PowerShell) ou web.ServerRelativeUrl (CSOM). Armazene esse valor em uma variável.
3. Construa o caminho relativo ao servidor completo
   Combine a URL relativa ao servidor do web com o caminho relativo do recurso. Exemplo: $web.ServerRelativeUrl + '/Listas/MinhaLista'. Não inclua o domínio absoluto.
4. Valide a URL final
   Verifique se a URL combinada começa com a URL relativa ao servidor do web. Se não começar, ajuste o caminho do recurso para ser relativo à raiz do web.

Método 3: Corrigir URLs em Layouts de Página e Master Pages

1. Use o token ~sitecollection
   No SharePoint Designer ou HTML, substitua caminhos codificados por ~sitecollection ou ~site. O token ~sitecollection resolve para a URL relativa ao servidor do conjunto de sites. O token ~site resolve para a URL relativa ao servidor do site atual.
2. Reescreva URLs absolutas
   Se um link usar uma URL absoluta como https://contoso.sharepoint.com/sites/MeuSite/Paginas/Home.aspx, altere para ~site/Paginas/Home.aspx. Isso garante que o link funcione em qualquer site dentro do conjunto.
3. Teste com um sub-site
   Navegue até um sub-site e verifique se todos os links e recursos carregam sem o erro. Se o erro persistir, verifique se o token resolveu para o caminho correto.

Se o Erro Persistir Após a Correção Principal

“Server Relative URL Must Start With SPWeb Server Relative URL” no SharePoint Designer

Ao editar uma página no SharePoint Designer, você pode ver esse erro após alterar a URL de um recurso vinculado. A causa geralmente é uma URL codificada em uma web part Data View ou em um hiperlink. Para corrigir, abra a página no modo avançado, encontre a URL do recurso e substitua por um token ou uma URL relativa ao servidor que comece com o caminho do site atual. Use ~site para recursos que devem seguir o site atual.

Erro ao Adicionar uma Web Part Programaticamente

Se você adicionar uma web part via código e fornecer uma URL relativa ao servidor para uma propriedade como ContentLink, certifique-se de que a URL seja relativa ao web onde a web part está sendo adicionada. Por exemplo, se você adicionar uma web part a um sub-site em /sites/MeuSite/Subsite, a URL deve começar com /sites/MeuSite/Subsite. Um erro comum é usar o caminho raiz do conjunto de sites. Sempre obtenha a URL relativa ao servidor do web atual dinamicamente.

Validação de URL no Painel de Propriedades do SharePoint Framework

No SPFx, se você tiver um campo no painel de propriedades que aceita uma URL relativa ao servidor, o usuário pode inserir um valor incorreto. Adicione validação à sua web part que verifique se a URL inserida começa com this.context.pageContext.web.serverRelativeUrl. Se não começar, mostre uma mensagem de erro e impeça a renderização da web part. Isso captura o problema antes que o erro ocorra.

URL Relativa ao Servidor vs URL Absoluta vs URL Relativa ao Site

Item	URL Relativa ao Servidor	URL Absoluta	URL Relativa ao Site
Formato	/sites/MeuSite/Paginas/Home.aspx	https://contoso.sharepoint.com/sites/MeuSite/Paginas/Home.aspx	/Paginas/Home.aspx
Inclui domínio	Não	Sim	Não
Inclui caminho gerenciado	Sim	Sim	Não
Funciona entre conjuntos de sites	Sim	Sim	Não
Funciona entre sub-sites	Sim	Sim	Não
Caso de uso comum	APIs, SPFx, CSOM	Links externos, e-mails	Navegação no mesmo site, imagens

O erro se aplica apenas a URLs relativas ao servidor. Se você usar uma URL absoluta, o SharePoint geralmente a aceita, mas ainda pode lançar o erro se o código esperar explicitamente uma URL relativa ao servidor. A abordagem mais segura é sempre usar URLs relativas ao servidor construídas a partir do contexto do web atual.

Agora você pode identificar e corrigir o erro “Server relative URL must start with SPWeb server relative URL”. Sempre use métodos dinâmicos para obter a URL relativa ao servidor do web atual, seja no SPFx, PowerShell ou layouts de página. Para soluções complexas, teste tanto em sites raiz quanto em sub-sites para detectar incompatibilidades de caminho precocemente. Uma prática confiável é armazenar a URL relativa ao servidor do web em uma variável no início do código e precedê-la a cada caminho de recurso.